Poetry 成功安装依赖但对应 CLI 命令仍报 command not found，通常因虚拟环境未正确激活、可执行文件未纳入 PATH，或依赖未声明为可执行入口点所致。本文详解排查步骤与可靠修复方案。

poetry 成功安装依赖但对应 cli 命令仍报 `command not found`，通常因虚拟环境未正确激活、可执行文件未纳入 path，或依赖未声明为可执行入口点所致。本文详解排查步骤与可靠修复方案。

Poetry 默认将依赖安装到项目专属虚拟环境中，但并不会自动将该环境中可执行脚本（如 deptry）暴露到系统 Shell 的 PATH 中——这是导致 command not found 的最常见原因。即使 poetry install 显示成功、poetry.lock 已生成、依赖也出现在 pyproject.toml 中，若未通过 Poetry 正确调用命令，Shell 就无法识别。

✅ 正确调用方式（推荐）：
使用 poetry run 显式在项目环境中执行命令：

poetry run deptry .
# 或检查是否识别
poetry run which deptry  # 应输出类似 /path/to/venv/bin/deptry

✅ 替代方式：激活虚拟环境后直接调用（需确保已初始化 shell）
先运行（仅需一次，按 Shell 类型选择）：

# Bash/Zsh
poetry shell

# 或手动激活（Poetry 1.7+ 推荐）
source $(poetry env info --path)/bin/activate

激活后即可直接运行：

deptry .

⚠️ 注意事项：

• deptry 是一个提供 CLI 入口点（entry point）的工具，其可执行脚本由 Poetry 在安装时自动生成于虚拟环境的 bin/ 目录下（如 venv/bin/deptry），不会全局安装到 /usr/local/bin 等系统路径。
• 若执行 poetry install 后仍提示 The following packages are already present... will be skipped，说明 Poetry 认为依赖已满足，但不保证可执行文件已注册——此时可强制重装：

  poetry update deptry  # 更新单个包并刷新 lock
  # 或彻底重建（更彻底）：
  poetry env remove python  # 删除当前虚拟环境
  rm poetry.lock
  poetry install

? 验证安装完整性：

poetry show deptry        # 查看包信息与版本
poetry run python -c "import deptry; print(deptry.__version__)"  # 验证模块可导入

? 总结：
command not found 不代表安装失败，而是环境隔离机制的正常体现。始终优先使用 poetry run <cmd></cmd> 调用项目依赖的 CLI 工具；避免依赖全局 PATH 注入。如需频繁使用，可配置别名（如 alias deptry='poetry run deptry'），但切勿手动软链 venv/bin/deptry 到 /usr/local/bin——这会破坏环境隔离性与可复现性。