Poetry：Python 依赖管理，一个工具就够了

Poetry：Python 依赖管理，一个工具就够了

python-poetry/poetry 在 GitHub 上已经拿到 34.3K Star 了。

Python 的打包和依赖管理一直是个痛点。setup.py、requirements.txt、setup.cfg、MANIFEST.in、Pipfile……光是把这些文件列出来就够让人头疼的。Poetry 做的事情很直接：用一个 pyproject.toml 替代上面所有文件，把声明依赖、管理虚拟环境、打包发布这些事统一到一个工具里。

1、Poetry 解决什么问题

Python 依赖管理工具的演变路径大概是这样的：从最原始的 pip + requirements.txt，到 Pipenv 试图统一 Pipfile 和 Pipfile.lock，再到今天 Poetry 成为事实标准。

核心问题是 Python 官方一直没有像 npm 之于 Node.js、Cargo 之于 Rust 那样提供一个一站式工具。每个 Python 项目一立项就得纠结选哪套方案，而 Poetry 正在终结这种选择困难。

Poetry 基于 PEP 517 和 PEP 518 标准构建，用 pyproject.toml 统一管理项目元数据、依赖声明、构建配置。它自带依赖解析器，能算出无冲突的依赖树并生成 lock 文件，确保开发、CI、生产环境的一致性。

2、pyproject.toml 长什么样

Poetry 的核心就是一个声明式的配置文件。依赖支持版本约束、extras、git 源、路径引用，还能按 group 分组管理，不至于把所有依赖塞进一个列表。

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "The description of the package"

[tool.poetry.dependencies]
python = ">=3.8"
aiohttp = "^3.8.1"
requests = { version = "^2.28", extras = ["security"] }

[tool.poetry.group.dev.dependencies]
pytest = "^7.1.2"
pytest-cov = "^3.0"

3、日常工作流

Poetry 的常用命令不超过 10 个，覆盖了开发到发布的完整流程：

poetry new my-project          # 创建新项目
poetry add requests            # 添加依赖
poetry install                 # 安装所有依赖并创建虚拟环境
poetry update                  # 更新依赖到最新兼容版本
poetry build                   # 构建 wheel 和 sdist
poetry publish                 # 发布到 PyPI

poetry.lock 文件锁定每个依赖的精确版本和哈希值，提交到 Git 后，团队所有人跑 poetry install 拿到的依赖完全一致。对于 entrypoint 和 script，在 pyproject.toml 里声明 [tool.poetry.scripts] 即可，不需要再写 setup.py 里的 console_scripts 配置。

4、适合哪些人用

Poetry 适用于几乎所有 Python 项目，但下面几种场景收益最大：

• 团队协作项目，需要锁死依赖版本，避免"我机器上能跑"的问题
• 要发布到 PyPI 的开源库，poetry build 和 publish 比手动 setup.py 方便太多
• CI/CD 管线，lock 文件保证每次构建的依赖确定且可复现
• 用 monorepo 管理的多包项目，Poetry 的 path dependency 和插件体系能简化编排

5、生态和插件

Poetry 周边有几个官方维护的配套项目：poetry-core 提供 PEP 517 构建后端和核心功能；poetry-plugin-export 能把 lock 文件导出为 requirements.txt；poetry-plugin-bundle 支持打包到虚拟环境等外部格式。官方安装脚本和网站也都是独立维护的项目，整个生态在持续演进。

如果你还在 requirements.txt 和 setup.py 之间来回折腾，Poetry 值得花一个下午迁移试试。