使用Poetry管理Python项目时Sphinx命令无法识别的问题

问题场景 #

在使用Poetry管理的Python项目中执行poetry run sphinx-quickstart时，收到错误：

'sphinx-quickstart' is not recognized as an internal or external command,
operable program or batch file.

项目的pyproject.toml配置如下：

[tool.poetry]
name = "testing-project"
version = "0.1.0"
description = ""
authors = ["User  <user@gmail.com>"]
readme = "README.md"
packages = [{include = "testing_project"}]

[tool.poetry.dependencies]
python = "^3.9"
Sphinx = { version = "4.2.0", optional = true }
sphinx-rtd-theme = { version = "1.0.0", optional = true }
sphinxcontrib-napoleon = { version = "0.7", optional = true }
cython = "^0.29.35"

[tool.poetry.extras]
docs = ["Sphinx", "sphinx-rtd-theme", "sphinxcontrib-napoleon"]

[build-system]
requires = ["poetry-core"]

项目目录结构：

.
├── Testing_project
│   ├── testing_project
│   │   └── __init__.py
│   ├── docs
│   ├── poetry.lock
│   ├── pyproject.toml
│   └── tests
│       └── __init__.py
└── README.md

已通过pip show sphinx确认全局环境安装了Sphinx，但Poetry项目内仍无法识别该命令，且不打算使用Poetry虚拟环境，将采用Docker管理环境。

错误原因 #

• 可选依赖未被安装：你将Sphinx及相关文档依赖标记为optional = true，并归类到docs extras组中。Poetry默认只会安装非可选的核心依赖，不会自动安装extras里的可选依赖，因此项目环境中实际未包含Sphinx。
• Poetry环境隔离机制：Poetry默认会与全局Python环境隔离，即使全局安装了Sphinx，Poetry也不会调用全局环境中的命令，只会使用自身管理的项目依赖。

解决办法 #

1. 安装包含docs extras的依赖 #

执行以下命令，让Poetry安装包含docs组的所有依赖：

poetry install --extras docs

安装完成后，再执行poetry run sphinx-quickstart即可正常识别命令。

2. 调整依赖配置（移除可选标记） #

如果不需要将文档依赖设为可选，可以修改pyproject.toml的依赖部分，去掉optional = true：

[tool.poetry.dependencies]
python = "^3.9"
Sphinx = "4.2.0"
sphinx-rtd-theme = "1.0.0"
sphinxcontrib-napoleon = "0.7"
cython = "^0.29.35"

然后执行poetry install完成依赖安装，之后即可正常调用Sphinx命令。

3. Docker环境下的配置方案 #

在Dockerfile中集成Poetry依赖安装逻辑，确保构建镜像时包含docs相关依赖：

FROM python:3.9

WORKDIR /app

# 安装Poetry
RUN pip install poetry

# 复制依赖配置文件
COPY pyproject.toml poetry.lock ./

# 安装包含docs extras的项目依赖（--no-root避免提前安装项目本身）
RUN poetry install --extras docs --no-root

# 复制项目代码
COPY . .

构建镜像后，运行容器时即可直接执行sphinx-quickstart或poetry run sphinx-quickstart命令。

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