Python Poetry使用教程

1. Poetry 简介

Poetry 是一个现代化的 Python 依赖管理和打包工具，它解决了传统 pip + requirements.txt 方式的诸多痛点：

• 自动依赖解析（避免版本冲突）
• 虚拟环境管理（无需手动 virtualenv）
• 项目打包与发布（一键发布到 PyPI）
• 统一配置文件（pyproject.toml 替代 setup.py + requirements.txt）

本教程将带你从 安装配置 到 高级用法，全面掌握 Poetry 的使用。

---

2. 安装与配置

(1) 安装 Poetry

# Linux/macOS
curl -sSL https://install.python-poetry.org | python3 -

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

安装完成后，检查版本：

poetry --version

(2) 基本配置

# 让虚拟环境创建在项目目录内（推荐）
poetry config virtualenvs.in-project true

# 启用并行安装（加速依赖安装）
poetry config installer.parallel true

# 查看所有配置
poetry config --list

关键配置项：

• virtualenvs.path：虚拟环境存储路径（默认在系统缓存目录）
• installer.parallel：是否启用并行安装
• virtualenvs.in-project：是否在项目目录创建 .venv

---

3. 项目管理

(1) 创建新项目

# 创建标准项目结构
poetry new my-project

# 进入项目
cd my-project

生成的项目结构：

my-project/
├── pyproject.toml  # 项目配置文件
├── README.md
├── my_project/     # 源码目录
│   └── __init__.py
└── tests/          # 测试目录
    └── __init__.py

(2) 在现有目录初始化

poetry init

交互式输入：

• 项目名称、版本、描述
• Python 兼容版本
• 依赖项（可稍后添加）

---

4. 依赖管理

(1) 添加依赖

# 添加生产依赖
poetry add requests

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

# 指定版本范围
poetry add "django>=4.0,<5.0"

# 添加可选依赖（如 redis）
poetry add --optional redis

(2) 安装依赖

# 安装所有依赖（含开发依赖）
poetry install

# 仅安装生产依赖
poetry install --no-dev

(3) 更新与移除依赖

# 更新所有依赖
poetry update

# 更新指定包
poetry update requests

# 移除依赖
poetry remove requests

(4) 查看依赖

# 查看已安装的包
poetry show

# 树形结构显示依赖关系
poetry show --tree

# 检查过时的包
poetry show --outdated

---

5. 虚拟环境管理

(1) 创建与使用

# 使用指定 Python 版本创建虚拟环境
poetry env use python3.9

# 进入虚拟环境 Shell
poetry shell

# 在虚拟环境中运行命令（不进入 Shell）
poetry run python app.py

(2) 管理虚拟环境

# 列出所有虚拟环境
poetry env list

# 显示当前环境信息
poetry env info

# 删除虚拟环境
poetry env remove python3.9

---

6. 构建与发布

(1) 构建项目

# 生成 dist/ 下的安装包
poetry build

# 只构建 wheel 包
poetry build --format wheel

(2) 发布到 PyPI

# 配置 PyPI Token
poetry config pypi-token.pypi your-token

# 发布到 PyPI
poetry publish

# 发布到测试 PyPI
poetry publish --repository testpypi

(3) 版本管理

# 查看当前版本
poetry version

# 升级版本号
poetry version patch  # 0.1.0 → 0.1.1
poetry version minor  # 0.1.1 → 0.2.0
poetry version major  # 0.2.1 → 1.0.0

---

7. 高级功能

(1) 多包源管理

# 添加私有源
poetry source add private-repo https://private.pypi.org/simple

# 查看已配置的源
poetry source show

# 移除源
poetry source remove private-repo

(2) 导出 requirements.txt

# 导出生产依赖
poetry export --without-hashes --output requirements.txt

# 导出开发依赖
poetry export --dev --output requirements-dev.txt

(3) 插件管理

# 安装插件（如 poetry-plugin）
poetry self add poetry-plugin

# 查看已安装插件
poetry self show plugins

# 更新 Poetry 自身
poetry self update

---

8. 常见问题

(1) 依赖解析失败

# 强制更新 lock 文件
poetry lock --no-update

# 调试依赖冲突
poetry debug resolve

(2) 清理缓存

# 查看缓存列表
poetry cache list

# 清理所有缓存
poetry cache clear --all

(3) 虚拟环境问题

# 删除并重建虚拟环境
poetry env remove python3.9
poetry install

---

9. 最佳实践（补充）

---

10. 总结

Poetry 是 Python 项目管理的终极工具，它能：
✅ 自动处理依赖冲突
✅ 统一管理虚拟环境
✅ 简化打包与发布流程
✅ 替代 setup.py + requirements.txt

建议所有 Python 开发者迁移到 Poetry，享受更高效的开发体验！ 🚀