Poetry

Poetry 是 Python 的现代依赖管理工具，提供 All-in-one 的项目管理、依赖锁定和打包发布功能。

#resource #evergreen #python #python

[!info] related notes

所属 MOC: Python MOC, 开发环境 MOC

前置概念: virtualenv, python

并列概念: virtualenv, uv

关系笔记: python-package-management-evolution

Poetry

一句话定义

Poetry 是 Python 的现代依赖管理工具，是一个 All-in-one 的项目管理工具，集成虚拟环境创建、依赖管理、打包和发布到 PyPI 的全流程。

核心内容

解决什么问题

Poetry 把依赖声明、解析、锁定、环境安装和发布整合起来。pip + requirements 也可固定版本与哈希，但这些步骤需另行组织；不能把 requirements 一概视为“无法锁定”。

核心机制

配置文件：

pyproject.toml：项目配置和依赖声明（标准化）
poetry.lock：记录解析结果；安装仍受 Python、平台、markers、extras 与选定依赖组影响

设计理念：

引入现代语言（如 Rust 的 Cargo、Node 的 npm）的包管理理念
严格的依赖解析算法
集成虚拟环境管理

核心优势

依赖锁定：相同兼容环境与选择条件下，可从锁文件恢复依赖；不是跨平台环境逐字节相同的保证
依赖解析：求解兼容的版本约束；无解或元数据错误时仍可能失败
私有仓库支持好：企业环境友好
打包发布简单：一键发布到 PyPI
标准化配置：pyproject.toml 承载构建配置与项目元数据；PEP 518/621 分别约定对应部分

最小例子

安装 Poetry

# 推荐使用官方安装脚本
curl -sSL https://install.python-poetry.org | python3 -

# 或使用 pipx
pipx install poetry

# 或使用包管理器（Windows Scoop）
scoop install poetry

创建新项目

# 创建新项目
poetry new my-project
cd my-project

当前 Poetry 2.x 默认 src 布局（旧版示例可能使用平铺布局）：

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

在现有项目中初始化

cd existing-project
poetry init

管理依赖

# 添加依赖
poetry add requests

# 添加开发依赖
poetry add --group dev pytest

# 安装选定依赖组（默认含非 optional 组）及当前项目
poetry install

# 更新依赖
poetry update

# 查看依赖树
poetry show --tree

运行项目

# 验证创建出的项目可导入
poetry run python -c "import my_project; print(my_project.__file__)"

# 输出当前 shell 对应的激活命令；需在该 shell 中执行输出
poetry env activate

打包发布

# 构建
poetry build

# 发布到 PyPI
poetry publish

Poetry 2.x 的 poetry shell 已移至 poetry-plugin-shell 插件；只运行项目命令时无需激活或安装该插件。

pyproject.toml 示例（旧版配置，保留用于维护现有项目）

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
black = "^22.0.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

常用命令速查

命令	作用
`poetry new <name>`	创建新项目
`poetry init`	在现有项目初始化
`poetry add <package>`	添加依赖
`poetry add --group dev <package>`	添加开发依赖
`poetry install`	按锁文件和依赖组选择安装
`poetry sync`	同步选定依赖并移除环境中的多余包
`poetry update`	更新依赖
`poetry remove <package>`	移除依赖
`poetry show`	查看依赖列表
`poetry show --tree`	查看依赖树
`poetry env activate`	输出激活命令
`poetry shell`	启动激活环境的子 shell，需 shell 插件
`poetry run <command>`	在虚拟环境中运行命令
`poetry build`	构建项目
`poetry publish`	发布到 PyPI
`poetry lock`	同步锁文件；2.x 默认保留已锁版本，全部重新求解用 —regenerate
`poetry env info`	查看环境信息

边界与易混淆点

局限性

复杂约束、网络与冷缓存可能增加解析/安装成本，需结合项目实测
规则严格：不符合规范的包可能导致报错
学习曲线：比 pip + venv 更复杂

不是

不是始终调用 pip 的封装：当前 wheel 安装由独立 installer 完成，部分路径可能使用 pip
与 virtualenv 职责不同：Poetry 管项目契约，环境创建是其中一环
不用固定速度倍率选工具：应测量当前项目的冷/热缓存安装和解析成本

最佳实践

使用 pyproject.toml：标准化项目配置
提交 poetry.lock：确保团队依赖一致
分离依赖组：使用 --group dev 管理开发依赖
安装包源用 poetry source / tool.poetry.source；发布目标用 repositories 配置，不能混为一谈

适用场景

✅ 需要发布到 PyPI 的开源库
✅ 企业私有仓库环境
✅ 需要严格的依赖解析
✅ 团队已熟悉 Poetry 工作流
✅ 大型成熟项目
简单脚本可只用 venv + 安装工具；性能敏感的 CI 可实测比较 uv
新项目可比较 Poetry 与 uv，已有项目优先延续其锁文件和发布契约

参考：Poetry basic usage、环境管理、CLI。