Python项目管理工具：Poetry 使用指南
内容提要
Poetry 是基于 pyproject.toml 的 Python 依赖管理与打包工具。本文介绍其安装、常用命令、项目创建、依赖增删、虚拟环境与 Python 版本管理、依赖分组、poetry.lock 锁定及同步更新等完整工作流，并与 pip 对比，指出库项目应谨慎锁定依赖版本。
延伸解读
Poetry 与 pip 的关键差异
文章指出，poetry add 和 pip install 都会解析依赖，但 poetry remove 会删除依赖的库，而 pip uninstall 只删除指定库。此外，Poetry 通过 poetry.lock 锁定所有直接和间接依赖的精确版本，poetry sync 还能清理环境中未记录的依赖，使虚拟环境与锁文件保持一致。这些差异意味着 Poetry 更强调环境的一致性和可重复性，适合需要严格依赖管理的项目。
库项目为何要谨慎锁定依赖
文章特别提醒，如果开发的是库（library）而非应用（application），往往不需要将 poetry.lock 上传到版本管理仓库。因为库需要保持对多个依赖版本的兼容性，如果写死版本，很可能导致下游用户产生依赖冲突。相反，应用型项目则建议上传 pyproject.toml 和 poetry.lock，以确保部署环境一致。这一区分是使用 Poetry 时容易忽略但非常重要的实践边界。
依赖分组与安装选项的实用逻辑
Poetry 支持通过 --group 创建 dev、test 等可选依赖组，默认 install 会安装所有组。文章演示了 --with、--without、--only 的用法，并指出 --only 会忽略 --with 和 --without。对于生产环境，可以使用 --without=test 或 --only=main 来保持最精简的依赖。合理划分依赖组有助于减小生产环境体积，并让开发、测试依赖的管理更清晰。
虚拟环境位置对多版本测试的影响
文章说明，当 virtualenvs.in-project 为 true 时，虚拟环境固定在项目下的 .venv，无法为同一项目保留多个 Python 版本环境；而设为 false 时，虚拟环境存放在用户缓存目录，可以通过 poetry env use 为不同 Python 版本创建独立环境，方便切换测试。但需注意，指定的 Python 版本必须符合 pyproject.toml 中 requires-python 的约束。这一配置选择直接影响多版本兼容性验证的便利性。
Q&A
Poetry 是什么？它和 pyproject.toml 有什么关系？
Poetry 是用于 Python 的依赖管理和打包工具，设计目标是简化和提升 Python 包的创建、管理与发布过程。它基于 pyproject.toml 文件实现大部分管理功能，该文件由 PEP 518 和 PEP 621 等规范定义，用于项目依赖、构建和元信息管理。
如何安装 Poetry？推荐使用什么方式？
安装方法见官方文档 https://python-poetry.org/docs，不同平台有各自的安装方法，建议使用 pipx 安装：pipx install poetry。升级使用 pipx upgrade poetry。
Poetry 的常用命令有哪些？
常用命令包括：poetry new（创建项目）、poetry init（初始化现有项目）、poetry add（添加依赖）、poetry remove（移除依赖）、poetry install（安装依赖）、poetry sync（同步依赖）、poetry run（在虚拟环境中运行命令）。此外还有 poetry list、poetry about 等辅助命令。
Poetry 如何管理项目的 Python 版本和虚拟环境？
Poetry 支持通过 poetry python install 安装特定版本的 Python，使用 poetry env use 切换虚拟环境的 Python 版本。虚拟环境位置由配置 virtualenvs.in-project 决定：为 true 时在项目目录下的 .venv，为 false 时在用户目录的 .cache/pypoetry/virtualenvs，后者可支持多版本测试。
poetry.lock 文件有什么作用？库项目需要提交它吗？
poetry.lock 记录了当前项目所有依赖包的精确版本信息，相当于依赖快照，poetry sync 等命令会读取它还原一致的依赖环境。对于库项目，往往不需要上传 poetry.lock 到版本管理仓库，因为库需要保持多个依赖版本的兼容性，写死版本可能导致依赖冲突。
Poetry 的依赖分组是什么？如何使用？
依赖分组用于区分不同用途的依赖，例如 dev 组用于开发工具，test 组用于测试。使用 poetry add --group dev ruff 添加 dev 组依赖。安装时默认安装所有组，可用 --with 安装可选组，--without 排除可选组，--only 只安装某些组。
poetry install 和 poetry sync 有什么区别？
poetry install 安装 poetry.lock 中的所有依赖，且只安装环境中缺失的部分；poetry sync 除了安装和同步依赖外，还会清理环境中未被 poetry.lock 记录的依赖，使虚拟环境与 lock 文件完全一致。
如何更新 Poetry 项目中的依赖版本？
使用 poetry update 更新依赖，可指定包名或更新所有依赖。若要突破 pyproject.toml 中的版本限制，需使用 poetry add 并指定新的版本约束，例如 poetry add "aiohttp<3.10"，这会重新解析并升级到符合条件的版本。
