Python 依赖锁文件的版本管理策略

2次阅读

pip-tools 生成的 requirements.txt 每次 pip-compile 都变,因默认不锁定子依赖版本,上游补丁更新即触发变更;需显式声明间接依赖或配合 –generate-hashes 才能固定全部版本。

Python 依赖锁文件的版本管理策略

pip-tools 生成的 requirements.txt 为什么每次 pip-compile 都变?

因为 pip-compile 默认不锁定子依赖的间接版本,只要上游包发布新补丁(比如 requests==2.31.0 升到 2.31.1),重编译就会更新——这看起来像“不稳定”,其实是设计使然。

  • --upgrade-strategy=eager 会主动升到最新兼容版,慎用;默认 only-if-needed 更保守
  • 想固定全部版本,必须在 requirements.in 里显式写出间接依赖,或配合 --generate-hashes + --allow-unsafe(但后者会把 setuptools 这类工具包也锁死,CI 中可能出问题)
  • 常见误操作:把 pip-tools 当成“一键锁死”工具,却没意识到它只保证直接依赖的语义版本范围生效

poetry.lock 和 pyproject.toml 的版本字段冲突怎么处理?

pyproject.toml 里写 django = "^4.2",而 poetry.lock 已存 django = "4.2.12",此时改 pyproject.tomldjango = "^4.3" 后运行 poetry update,Poetry 不会自动降级已安装的旧版,也不会立刻重装——它只更新 lock 文件,下次 poetry install 才真正生效。

  • 本地开发中删掉 __pycache__.venv 后直接 poetry install,才能确保环境和 lock 严格一致
  • CI 流水线里如果跳过 poetry install、直接用 pip install -r requirements.txt(由 poetry export 生成),就绕过了 lock 文件校验,等于放弃 Poetry 的版本保障
  • poetry show --outdated 能列出可升级项,但它不检查 lock 文件是否过期,只对比远程索引

pip freeze > requirements.txt 在 CI 中为什么不可靠?

它输出的是当前环境里所有已安装包的精确版本,包括那些本不该进生产依赖的开发工具(blackmypy)、临时调试安装的包,甚至 pip 自身的版本。更危险的是,它不区分 install 来源——从 git、本地路径、wheel 安装的包会以非标准格式写入,导致下游 pip install -r 失败。

  • 永远不要在 CI 的构建阶段用 pip freeze 生成生产依赖文件
  • 如果必须用,至少加 --exclude-editable--not-required 过滤,但仍无法解决来源不一致问题
  • 替代方案:用 pipreqs 扫描 import 语句生成初始 requirements.in,再交由 pip-tools 编译,可控性高得多

Git 里该提交 poetry.lock 还是 requirements.txt

两者定位不同:poetry.lock 是 Poetry 项目事实上的依赖快照,必须提交;而 requirements.txt 是导出产物,属于中间文件,不应进 Git,除非你明确把它当作部署唯一入口(例如某些 paas 平台只认这个文件)。

立即学习Python免费学习笔记(深入)”;

  • 团队协作时,只提交 poetry.lock,其他人 poetry install 就能复现完全一致环境
  • 如果部署流程强制要求 requirements.txt,用 poetry export -f requirements.txt --without-hashes > requirements.txt 生成,并在 CI 中完成,而不是手动生成后提交
  • 容易被忽略的一点:poetry.lock 里包含平台标记(如 markers = "platform_system == 'linux'"),跨平台开发时若没注意,windows 开发者生成的 lock 文件可能导致 Linux 构建失败
text=ZqhQzanResources