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，享受更高效的开发体验！ 🚀