使用Poetry构建项目时出现No module named 'pybind11'错误的原因

问题场景 #

之前通过子模块配合CMake使用pybind11一切正常，现在基于Poetry开发新项目，尝试构建示例项目时出现以下错误：

Preparing build environment with build-system requirements poetry-core>=1.0.0
Building poetry-pybind11-integration (0.1.0)
Traceback (most recent call last):
File "/blah/poetry-pybind11-integration/build.py", line 1, in
from pybind11.setup_helpers import Pybind11Extension, build_ext
ModuleNotFoundError: No module named 'pybind11'

已知build.py首行导入了pybind11相关模块，且pybind11已在pyproject.toml中声明。

核心原因 #

1. 依赖声明位置错误 #

如果pybind11仅被放在[tool.poetry.dependencies]区域，Poetry的构建环境无法访问这个依赖。pybind11.setup_helpers属于构建阶段必需的工具依赖，而非运行时依赖，必须配置在构建环境的专属依赖列表中。

2. Poetry构建环境的隔离机制 #

Poetry在构建包时会创建独立的临时环境，这个环境只会加载pyproject.toml中[build-system]部分指定的依赖。[tool.poetry.dependencies]下的依赖是为最终运行环境准备的，不会被自动加入到构建临时环境中，因此执行build.py时找不到pybind11模块。

解决方法 #

修改pyproject.toml，将pybind11添加到[build-system.requires]列表内，示例配置如下：

[build-system]
requires = ["poetry-core>=1.0.0", "pybind11>=2.10.0"]
build-backend = "poetry.core.masonry.api"

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