Poetry无法安装自定义CLI脚本的问题求助

环境配置 #

• 运行环境：MacOS、zsh、Python 3.10
• 项目结构：

- .venv
- pyproject.toml
- main.py
- src
   |...

• pyproject.toml关键配置：

[tool.poetry]
...
[tool.poetry.dependencies]
...
[tool.poetry.scripts]
my-cli="main:app"

• 执行步骤：
  1. python -m venv .venv
  2. pip install poetry
  3. source .venv/bin/activate
  4. poetry install

问题现象 #

执行poetry install后依赖已成功安装到.venv，但出现以下问题：

• 执行which my-cli返回my-cli not found
• 执行poetry run my-cli时弹出警告：

Warning: 'my-cli' is an entry point defined in pyproject.toml, but it's not installed as a script. You may get improper `sys.argv[0]`.

已尝试的解决方法 #

• 删除.venv重新创建，改用pipx安装Poetry
• 将main.py简化为仅输出"Hello World"的app函数
• 删除poetry.lock后重新执行安装
• 修改pyproject.toml中的脚本名称（如将my-cli改为abc）
• 移除[tool.poetry.scripts]段，删除poetry.lock和.venv，重新创建环境、安装Poetry并执行poetry install，再添加脚本段重新安装，结果提示No dependencies to install or update，脚本未被识别

解决方法 #

1. 强制以可编辑模式安装项目 #

Poetry的脚本需要将项目安装到虚拟环境中才会生成可执行文件，手动指定可编辑模式安装：

poetry install --editable

2. 明确指定项目包含的文件 #

如果main.py不在Poetry默认识别的包结构中，需要在pyproject.toml里添加packages配置，确保main.py被包含：

[tool.poetry]
# 确保name字段已正确设置，例如name = "my-cli-project"
packages = [{ include = "main.py" }]

修改后重新执行poetry install

3. 构建项目后安装 #

先构建项目生成wheel包，再安装到虚拟环境：

poetry build
pip install dist/*.whl

此操作会将可执行脚本直接安装到.venv/bin目录下。

4. 检查虚拟环境PATH配置 #

激活虚拟环境后，确认.venv/bin已加入系统PATH：

echo $PATH

如果未包含，手动添加：

export PATH="$PWD/.venv/bin:$PATH"

之后再尝试执行my-cli

内容的提问来源于stack exchange，提问作者HGLR