Poetry 是一款现代化的 Python 项目管理和打包工具。它将依赖管理、虚拟环境管理、打包和发布功能集成在一个直观的命令行界面中。Poetry 的核心理念是提供一个统一的、声明式的项目配置方式，以 pyproject.toml 文件 (遵循 PEP 518 和 PEP 621) 作为所有项目元数据和依赖的唯一真实来源。

核心思想：Poetry 旨在通过一个工具，简化 Python 项目从创建到发布的全生命周期管理，确保环境隔离、依赖可重现性和便捷的打包发布流程。

一、为什么需要 Poetry？

传统的 Python 项目管理方式通常涉及多个工具和手动步骤，带来了诸多痛点：

  • pip 和 requirements.txt 的局限性：
    • requirements.txt 仅记录直接依赖，不处理传递性依赖，容易导致环境不一致。
    • 缺乏强大的依赖解析能力，解决包版本冲突困难。
    • 没有统一的元数据管理，项目信息分散在 setup.py、README.md 等文件中。
  • 虚拟环境管理不便：
    • 需要手动创建 venv 或 virtualenv，并手动激活、切换。
    • 项目与虚拟环境的关联不够紧密。
  • 打包和发布复杂：
    • 传统的 setuptools 和 setup.py 配置复杂，尤其是对于非标准项目。
    • 发布到 PyPI 需要额外的工具如 twine。
  • 开发环境和生产环境不一致：
    • 由于缺乏精确的依赖锁定，开发时能运行的代码在生产环境可能因依赖版本差异而出现问题。
  • 工具碎片化：开发者需要同时管理 pip、venv、setuptools、twine 等多个工具。

Poetry 旨在通过以下方式解决这些问题：

  • 一体化解决方案：将依赖管理、虚拟环境、打包和发布集成到单一工具中。
  • 声明式配置：使用 pyproject.toml 统一管理项目元数据、依赖、脚本等，清晰明了。
  • 强大的依赖解析：内置高效的依赖解析器，自动处理版本冲突，生成精确的 poetry.lock 文件。
  • 自动化的虚拟环境管理：为每个项目自动创建和管理隔离的虚拟环境。
  • 简化打包发布：提供简单的命令即可构建和发布包。
  • 可重现性：通过 poetry.lock 确保团队成员和部署环境的依赖完全一致。

二、Poetry 的核心特性

2.1 依赖管理与锁定

Poetry 使用 pyproject.toml 文件定义项目的直接依赖，并自动解析所有传递性依赖。

  • pyproject.toml：作为项目配置的中心，定义了项目名称、版本、描述以及依赖项。
  • poetry.lock：由 Poetry 自动生成和维护，记录了项目及其所有传递性依赖的精确版本和哈希值，确保环境的完全可重现性。

2.2 虚拟环境管理

Poetry 为每个项目自动创建和管理一个独立的虚拟环境，通常存储在用户主目录下的 Poetry 缓存中，或者在项目根目录（可配置）。

  • 隔离性：每个项目的依赖都与系统或其他项目完全隔离。
  • 自动化：无需手动激活，Poetry 命令会自动在正确的虚拟环境中执行。

2.3 项目打包与发布

Poetry 简化了创建 Python 包并将其发布到 PyPI 的过程。

  • 构建：根据 pyproject.toml 中的元数据自动构建 sdist (源码分发) 和 wheel (二进制分发)。
  • 发布：可以直接将构建好的包发布到 PyPI 或其他私有仓库。

2.4 项目脚手架与脚本运行

Poetry 提供了创建新项目结构的命令，并允许在 pyproject.toml 中定义和运行自定义脚本。

  • poetry new：快速生成一个标准的项目目录结构。
  • poetry run：在项目虚拟环境中运行任意命令或脚本。

三、安装 Poetry

官方推荐使用专门的安装脚本，以避免与现有 Python 环境的冲突。

1
2
3
4
5
6
7
8
9
10
11
12
# Linux / macOS / WSL
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# 通过 pipx 安装 (如果你已经安装了 pipx)
pipx install poetry

# 验证安装
poetry --version
# Output: Poetry (version 1.x.x)

安装完成后，可能需要将 Poetry 的 bin 目录添加到系统 PATH 环境变量中。

四、Poetry 指令详解

Poetry 的命令行界面设计直观，所有命令都以 poetry 开头。

4.1 项目初始化与创建

  • poetry init: 在现有目录中交互式地初始化一个新 Poetry 项目，生成 pyproject.toml 文件。
    1
    2
    mkdir my_project && cd my_project
    poetry init # 按照提示输入项目信息和依赖
  • poetry new <project_name>: 创建一个具有标准目录结构的新 Poetry 项目。
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    poetry new my_app
    # 这将创建以下结构：
    # my_app/
    # ├── my_app/
    # │   └── __init__.py
    # ├── pyproject.toml
    # ├── README.md
    # └── tests/
    #     └── __init__.py
    #     └── test_my_app.py

4.2 依赖管理

  • poetry add <package_name> [version_constraint] [options]: 向项目中添加一个依赖包，并自动安装它，同时更新 pyproject.toml 和 poetry.lock。
    • [version_constraint]: 可以是 ~1.0 (兼容版本), ^1.0 (最小兼容版本), >=1.0,<2.0, ==1.0, 或 Git URL 等。
    • --group <group_name>: 将包添加为指定组的依赖（例如：dev, test, doc）。Poetry 1.2+ 推荐使用 --group，代替旧版的 --dev。
    • --group dev / --dev: (旧版Poetry) 将包添加为开发依赖。
    • --optional: 将包添加为可选依赖。
    • 示例：
      1
      2
      3
      4
      5
      poetry add requests                   # 添加 requests 作为主依赖
      poetry add "fastapi@^0.100.0"         # 添加特定版本范围的 fastapi
      poetry add "uvicorn[standard]@^0.23.0" # 添加带 extras 的包
      poetry add pytest --group dev         # 添加 pytest 作为开发依赖组
      poetry add black --group dev --optional # 添加可选的开发依赖
  • poetry remove <package_name> [options]: 从项目中移除一个依赖包，并自动卸载它，同时更新 pyproject.toml 和 poetry.lock。
    • --group <group_name>: 从指定依赖组中移除。
    • --group dev / --dev: (旧版Poetry) 从开发依赖中移除。
    • 示例：
      1
      2
      poetry remove requests
      poetry remove pytest --group dev
  • poetry install [options]: 从 poetry.lock 文件安装所有依赖。如果 poetry.lock 不存在，则根据 pyproject.toml 解析并生成 poetry.lock。
    • --no-root: 不安装当前项目自身（仅安装依赖）。
    • --sync: 卸载所有锁定文件中不存在的包，使环境与 poetry.lock 完全同步。
    • --only <group>: 只安装指定组的依赖。例如 --only main 只安装主依赖。
    • --with <group1> [--with <group2>]: 除了主依赖外，还安装指定组的依赖。
    • --without <group1> [--without <group2>]: 安装除了指定组之外的所有依赖。
    • --no-dev: (旧版Poetry) 不安装开发依赖。等同于 --without dev。
    • 示例：
      1
      2
      3
      4
      poetry install                                  # 安装所有依赖 (包括默认的开发依赖)
      poetry install --only main                      # 只安装主依赖
      poetry install --with dev,test                  # 安装主依赖和 dev、test 组依赖
      poetry install --without dev                    # 不安装 dev 组依赖
  • poetry update [package_name]: 更新依赖包到最新版本。如果未指定包名，则更新所有依赖。会更新 poetry.lock 文件。
    • 示例：
      1
      2
      poetry update # 更新所有依赖
      poetry update requests # 只更新 requests 包及其兼容依赖
  • poetry lock [--no-update]: 仅生成或更新 poetry.lock 文件，不安装任何包。
    • --no-update: 不更新现有的 poetry.lock，只检查 pyproject.toml 和 poetry.lock 是否同步。

4.3 环境管理与命令执行

  • poetry run <command> [args...]: 在当前项目虚拟环境中执行任意命令。
    • 示例：
      1
      2
      3
      poetry run python my_script.py
      poetry run pytest tests/
      poetry run black .
  • poetry shell: 激活当前项目的虚拟环境。进入一个子 shell，所有后续命令都将在该虚拟环境中执行。
    • 要退出虚拟环境，输入 exit。
    • 示例：
      1
      2
      3
      poetry shell
      # (my-project-venv) $ python my_script.py
      # (my-project-venv) $ exit
  • poetry env list [--full-path]: 列出当前项目关联的所有虚拟环境。
  • poetry env use <python_executable_or_env_name>: 将当前项目关联到指定的 Python 解释器或虚拟环境。
    • 示例：
      1
      2
      poetry env use python3.11   # 使用系统中的 python3.11 创建或切换虚拟环境
      poetry env use /path/to/venv/bin/python # 使用特定路径的解释器
  • poetry env remove <env_name>: 移除一个或多个虚拟环境。
  • poetry env info [--path]: 显示当前虚拟环境的信息。
  • poetry python: 显示当前项目使用的 Python 解释器的路径。

4.4 包信息与检查

  • poetry show [--tree] [--latest] [--outdated]: 显示项目依赖的列表。
    • --tree: 以树形结构显示依赖关系。
    • --latest: 显示包的最新版本。
    • --outdated: 显示已过时的包。
    • 示例：
      1
      2
      3
      poetry show
      poetry show --tree
      poetry show --outdated
  • poetry check: 检查 pyproject.toml 文件的语法和有效性。

4.5 打包与发布

  • poetry build [--format <format>]: 构建项目包的源码分发 (sdist) 和 Wheel 分发 (wheel)。
    • --format: 指定构建格式，例如 sdist, wheel。
    • 构建结果通常在项目根目录的 dist/ 文件夹中。
    • 示例：
      1
      2
      poetry build
      poetry build --format sdist
  • poetry publish [--repository <repo_name>] [--username <username>] [--password <password>]: 将构建好的包发布到 PyPI 或其他配置的仓库。
    • 在发布前，通常需要使用 poetry config 配置 PyPI 凭据。
    • 示例：
      1
      2
      poetry publish --build # 构建并发布
      poetry publish --repository my-custom-repo # 发布到自定义仓库

4.6 配置管理

  • poetry config <setting_key> <value>: 设置 Poetry 的配置选项。
    • --global: 将配置应用于所有项目。
    • 示例：
      1
      2
      3
      poetry config virtualenvs.in-project true # 在项目根目录创建 .venv 虚拟环境
      poetry config repositories.my-pypi https://my.pypi.org/simple/ # 添加自定义 PyPI 仓库
      poetry config pypi-token.pypi <your_pypi_token> # 配置 PyPI 认证令牌
  • poetry config --list: 列出所有配置项。

五、Poetry 的 pyproject.toml 结构

pyproject.toml 是 Poetry 项目的核心配置文件，它是一个TOML (Tom’s Obvious, Minimal Language) 格式的文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# pyproject.toml 示例
[tool.poetry]
name = "my-awesome-app"
version = "0.1.0"
description = "一个用Poetry管理的酷炫Python应用"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
packages = [{include = "my_awesome_app"}] # 明确指定包含哪些包到分发中

[tool.poetry.dependencies]
python = ">=3.9,<4.0" # Python 版本约束
requests = "^2.28.1"  # 主依赖
fastapi = {version = "^0.100.0", optional = true} # 可选依赖

[tool.poetry.group.dev.dependencies] # 开发依赖组 (Poetry 1.2+ 推荐)
pytest = "^7.0"
black = {version = "^23.0", optional = true}

[tool.poetry.group.doc.dependencies] # 文档依赖组
sphinx = "^5.0"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
  • [tool.poetry]: 定义了项目自身的元数据，如名称、版本、作者、描述、许可证等。
  • [tool.poetry.dependencies]: 定义了项目的运行时（主）依赖。python 键用于指定项目兼容的 Python 版本范围。
  • [tool.poetry.group.<group_name>.dependencies]: 定义了指定依赖组（如 dev, test, doc）的依赖。这些依赖通常不会在生产环境中安装，除非显式指定。
  • [build-system]: 这是 PEP 518 规范的一部分，用于声明构建此项目所需的工具和后端。对于 Poetry 项目，通常是 poetry-core。

六、Poetry 工作流

一个典型的 Poetry 项目开发工作流如下：

七、Poetry 的优缺点

7.1 优点：

  1. 统一的项目管理：集成了依赖、虚拟环境、打包、发布，简化开发流程。
  2. 严格的依赖锁定：poetry.lock 确保了环境的完全可重现性，解决“在我机器上能跑”的问题。
  3. 强大的依赖解析器：自动处理复杂的依赖版本冲突，减少手动干预。
  4. 清晰的配置：pyproject.toml 作为单一配置源，易于理解和维护。
  5. 自动化的虚拟环境：无需手动管理，Poetry 自动为项目提供隔离环境。
  6. 简化打包和发布：只需几个命令即可完成复杂的打包和发布流程。
  7. 现代标准兼容：拥抱 pyproject.toml (PEP 518, PEP 621) 等最新 Python 规范。

7.2 缺点：

  1. 学习曲线：对于习惯 pip + venv 传统工作流的用户，需要适应新的概念和命令。
  2. 性能考量：对于非常庞大或复杂的依赖图，Poetry 的依赖解析速度可能不如 Rust 编写的工具（如 uv）快。
  3. 与传统工具的兼容性：虽然可以导出 requirements.txt (poetry export)，但与纯 pip 或 setuptools 项目的集成可能需要额外步骤。
  4. 生态系统成熟度：虽然发展迅速，但某些高级或边缘用例可能不如 pip 生态系统那样全面覆盖。

八、总结

Poetry 是一款极具潜力的 Python 项目管理工具，它通过一体化、声明式和自动化的方法，极大地提升了 Python 项目的开发效率和可维护性。对于追求开发一致性、环境可重现性以及简化打包发布流程的开发者和团队来说，Poetry 是一个值得深入学习和采用的现代化解决方案。它代表了 Python 项目管理发展的未来方向，使得 Python 开发体验更加流畅和专业。