Poetry版本解析困惑：添加内部依赖时Python版本冲突排查

在使用Poetry管理项目依赖时，添加公司内部仓库的external-package时遭遇Python版本冲突报错。外部包的pyproject.toml指定Python版本要求为>=3.9,<3.10，当前项目的Python版本要求为^3.8，两者在3.9.x版本范围存在交集，但执行添加操作仍失败。

外部包依赖配置 #

[tool.poetry.dependencies]
python = ">=3.9,<3.10"
requests = "^2.28.2"
pandas = ">=1.5.0"
requests-toolbelt = "^1.0"  # "^0.10.1"
pyarrow = ">=16.1.0,<18"
polars = "^1.12.0"

当前项目依赖配置 #

[tool.poetry.dependencies]
python = "^3.8"
pandas = ">=1.5.0"
polars = "^1.12.0"
pyarrow = "<18.0.0"
seaborn = "^0.13.2"
matplotlib = "^3.9.2"
requests = "^2.28.2"

报错信息 #

The current project's supported Python range (>=3.8,<4.0) is not compatible with some of the required packages Python requirement:
  - external-package requires Python >=3.9,<3.10, so it will not be satisfied for Python >=3.8,<3.9 || >=3.10,<4.0

Because no versions of external-package match >0.1.24,<0.2.0
 and external-package (0.1.24) requires Python >=3.9,<3.10, external-package is forbidden.
So, because mhi-tools depends on external-package (^0.1.24), version solving failed.

  • Check your dependencies Python requirement: The Python requirement can be specified via the `python` or `markers` properties

    For external-package, a possible solution would be to set the `python` property to ">=3.9,<3.10"

核心原因 #

Poetry的依赖解析器会严格校验项目声明的Python版本范围是否完全覆盖依赖包的兼容范围，而非仅检查是否存在交集。当前项目的^3.8对应>=3.8,<4.0，包含了3.8.x和3.10+版本，而external-package不支持这些版本，因此解析器判定存在冲突，拒绝完成安装。

解决步骤 #

1. 缩小项目全局Python版本范围 #

直接修改项目pyproject.toml中的Python版本要求，使其与外部包的兼容范围完全匹配：

[tool.poetry.dependencies]
python = ">=3.9,<3.10"
# 其他依赖项保持不变

修改后执行poetry lock --no-update重新生成锁文件，再尝试添加外部包即可。

2. 为外部包单独添加版本约束标记 #

若不想调整项目全局的Python版本要求，可在添加外部包时通过markers指定其适用的Python版本范围，命令如下：

poetry add external-package@^0.1.24 --python ">=3.9,<3.10"

或手动在项目pyproject.toml中配置：

[tool.poetry.dependencies]
external-package = { version = "^0.1.24", python = ">=3.9,<3.10" }

这种方式会让Poetry仅在Python版本处于3.9.x范围时安装该包，不影响项目对其他Python版本的支持，但需注意项目在3.8.x或3.10+环境下无法使用此包。

3. 检查外部包是否有兼容更广版本的分支 #

查询公司内部仓库，确认external-package是否存在Python版本要求更宽松的版本（如>=3.8,<3.10），若有则直接安装该版本：

poetry add external-package@>=0.1.0,<0.2.0 --python ">=3.8,<3.10"

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