[!info] related notes

• 所属 MOC: python-moc, development-environment-moc
• 前置概念: virtualenv, python
• 并列概念: virtualenv, uv
• 关系笔记: python-package-management-evolution

Poetry

一句话定义

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

核心内容

解决什么问题

pip + requirements.txt 的组合存在明显缺陷：

• 没有依赖锁定机制
• 多人协作容易因子依赖版本不同而出问题
• 打包发布流程繁琐
• 缺乏标准化的项目配置

核心机制

配置文件：

• pyproject.toml：项目配置和依赖声明（标准化）
• poetry.lock：依赖锁定文件，确保版本精确一致

设计理念：

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

核心优势

1. 依赖锁定：poetry.lock 确保所有开发者安装的依赖版本精确一致
2. 依赖解析严谨：复杂的依赖树也能正确解析
3. 私有仓库支持好：企业环境友好
4. 打包发布简单：一键发布到 PyPI
5. 标准化配置：使用 pyproject.toml（PEP 518）

最小例子

安装 Poetry

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

# 或使用 pipx
pipx install poetry

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

创建新项目

# 创建新项目
poetry new my-project

# 项目结构
my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

在现有项目中初始化

cd existing-project
poetry init

管理依赖

# 添加依赖
poetry add requests

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

# 安装所有依赖
poetry install

# 更新依赖
poetry update

# 查看依赖树
poetry show --tree

运行项目

# 在虚拟环境中运行命令
poetry run python main.py

# 激活虚拟环境
poetry shell

打包发布

# 构建
poetry build

# 发布到 PyPI
poetry publish

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 update	更新依赖
poetry remove <package>	移除依赖
poetry show	查看依赖列表
poetry show --tree	查看依赖树
poetry shell	激活虚拟环境
poetry run <command>	在虚拟环境中运行命令
poetry build	构建项目
poetry publish	发布到 PyPI
poetry lock	更新 lock 文件
poetry env info	查看环境信息

边界与易混淆点

局限性

• 速度较慢：Python 编写 + 严格解析算法，复杂依赖时解析慢
• 规则严格：不符合规范的包可能导致报错
• 学习曲线：比 pip + venv 更复杂

不是

• 不是 pip 的替代品：底层仍然使用 pip 进行包安装
• 不是 virtualenv 的替代品：功能更全面，但也更重
• 不是最快的工具：uv 在速度上有 10-100 倍优势

最佳实践

1. 使用 pyproject.toml：标准化项目配置
2. 提交 poetry.lock：确保团队依赖一致
3. 分离依赖组：使用 --group dev 管理开发依赖
4. 使用私有仓库：配置 repositories

适用场景

• ✅ 需要发布到 PyPI 的开源库
• ✅ 企业私有仓库环境
• ✅ 需要严格的依赖解析
• ✅ 团队已熟悉 Poetry 工作流
• ✅ 大型成熟项目
• ❌ 追求极致速度的场景（用 uv）
• ❌ 简单脚本（用 venv）
• ❌ 新项目（推荐 uv）