Poetry 入门指南：Python 依赖管理与打包的现代方案
Poetry 是 Python 现代化的依赖管理与打包工具：项目脚手架、依赖解析锁定、依赖分组、虚拟环境管理与发布一体化。本文讲解核心用法与工作流。
直接回答：Poetry 把 Python 项目的依赖管理、虚拟环境、打包发布整合成一条顺滑流水线：pyproject.toml 声明、poetry.lock 锁定、依赖分组、一键发布 PyPI——一个工具顶过去一堆。
为什么用 Poetry
仅有宽松 requirements 约束时，每次解析可能不同；完整 pin 与 hash 可提高可复现性、直接与间接依赖不分、打包发布另学一套。Poetry 借鉴 npm/cargo 的体验，把这些整合为统一工具链。
安装
curl -sSL https://install.python-poetry.org | python3 -
# 或用 pipx 安装（推荐，隔离干净）
pipx install poetry
项目起步
poetry new myproj # 新项目脚手架
# 或已有项目
poetry init # 交互式生成 pyproject.toml
生成的 pyproject.toml 集中管理元数据与依赖——一份文件就是项目的完整身份证。
依赖管理
poetry add requests # 安装并锁定
poetry add pytest --group dev # 开发组
poetry remove requests
poetry install # 按 lock 还原环境
poetry update # 升级依赖
poetry show --tree # 依赖树
poetry.lock 锁定全部依赖（含间接）的精确版本与哈希，必须提交进版本库——它是"在我机器上能跑"的终结者。
依赖分组
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
ruff = "^0.5"
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
部署 poetry install --only main（只装运行时）；非 optional 分组默认安装；仅 optional 分组需 --with。CI 按需选择分组。分组比 requirements 拆分文件清晰得多。
虚拟环境
Poetry 自动创建并管理项目虚拟环境：
eval "$(poetry env activate)" # POSIX shell；Poetry 2.x
# poetry shell 需另装 poetry-plugin-shell
poetry run pytest # 免激活执行
poetry env list # 查看环境
构建与发布
poetry build # 产出 wheel 与 sdist
poetry publish # 发布到 PyPI（配好 token）
对库作者而言，Poetry 把"打包上传"整合为构建和上传两个步骤。
常见问题（FAQ）
Q：Poetry 和 uv 怎么选？
A：2026 年的现实：uv 提供另一套项目工作流，实际速度应按依赖与缓存测量；Poetry 工作流成熟、插件生态厚、团队存量大。新项目求快选 uv，团队已在 Poetry 上跑顺不必折腾。
Q：Docker 里怎么装依赖？
A：安装 poetry-plugin-export 后用 poetry export -f requirements.txt 导出给 pip，或容器内装 poetry 后 poetry install --only main——前者镜像更干净。
Q：Poetry 的解析器很慢怎么办？
A：先确认版本够新（近年大幅提速）；锁定后日常用 install（走 lock 不解析）。依赖约束写得越宽解析越慢，适当收紧主版本。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
