--- tags: - python --- 以下是一份 **Poetry 完全指南**，涵盖从安装到高级功能的全面教程，结合最佳实践和实用技巧： --- ### **1. 安装 Poetry
tags:
以下是一份 Poetry 完全指南，涵盖从安装到高级功能的全面教程，结合最佳实践和实用技巧：
1. 安装 Poetry
系统级安装（推荐）
1
2
3
4
5
|
# Linux/macOS
curl -sSL https://install.python-poetry.org | python3 -
# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
|
验证安装
1
|
poetry --version# 输出示例: Poetry (version 1.8.0)
|
配置中国镜像加速
1
|
poetry config repo.pypi.url https://pypi.tuna.tsinghua.edu.cn/simple/
|
️ 2. 项目管理
创建新项目
1
|
poetry new my-project && cd my-project
|
生成目录结构：
1
2
3
4
5
6
7
8
|
my-project/
├── pyproject.toml# 核心配置文件
├── README.md
├── src/
│└── my_project/
│└── __init__.py
└── tests/
└── test_my_project.py
|
初始化现有项目
1
2
|
cd existing-project
poetry init# 交互式生成 pyproject.toml
|
📦 3. 依赖管理
安装依赖
1
2
|
poetry install# 安装所有依赖（含开发依赖）
poetry install --no-dev# 仅生产依赖
|
添加/移除依赖
1
2
3
4
5
6
7
8
|
# 生产依赖
poetry add requests numpy@^1.24# 指定版本约束
# 开发依赖（测试/文档等）
poetry add --group dev pytest black
# 移除依赖
poetry remove pandas
|
锁定依赖版本
1
|
poetry lock# 生成 poetry.lock 确保版本一致性
|
🌐 4. 虚拟环境管理
自动创建环境（默认）
1
2
|
poetry env use python3.10# 指定Python版本
poetry shell# 激活虚拟环境
|
项目内建环境（推荐）
1
|
poetry config virtualenvs.in-project true# 创建 .venv 在项目内
|
常用命令
1
2
3
|
poetry env info# 查看环境信息
poetry env list# 列出所有环境
poetry env remove 3.10# 删除环境
|
🔧 5. 依赖分组（高级功能）
分组管理（测试/文档/性能）
1
2
3
4
5
6
7
|
# pyproject.toml
[tool.poetry.group.test.dependencies]
pytest = "^7.4"
coverage = "*"
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
|
安装指定组
1
2
|
poetry install --with test,docs# 安装多组依赖
poetry add --group perf pyinstrument# 添加新组
|
📦 6. 打包与发布
构建包
1
|
poetry build# 生成 dist/ 目录下的 .whl 和 .tar.gz
|
发布到 PyPI
1
2
3
4
5
|
# 配置 API Token
poetry config pypi-token.pypi your-token-here
# 发布
poetry publish
|
发布到私有仓库
1
2
3
4
|
# pyproject.toml
[[tool.poetry.source]]
name = "private"
url = "https://private-repo.example/simple"
|
1
|
poetry publish -r private
|
️ 7. 进阶配置
脚本别名
1
2
3
4
|
# pyproject.toml
[tool.poetry.scripts]
start = "my_project.main:run_app"
bench = "python benchmarks/main.py"
|
运行：poetry run start
多环境配置
1
2
|
# 条件依赖 (Windows专用)
pathlib2 = { version = "*", markers = "sys_platform == 'win32'" }
|
源码依赖
1
2
|
[tool.poetry.dependencies]
my-lib = { git = "https://github.com/user/repo.git", branch = "main" }
|
8. 故障排查
常见问题解决
1
2
3
4
5
6
7
8
9
|
# 重置环境
poetry env remove --all
poetry cache clear --all pypi
poetry lock --no-cache
poetry install
# 依赖冲突诊断
poetry show --tree
poetry show --latest | grep -v up-to-date
|
✅ 9. 最佳实践
- 锁定文件必提交：将
poetry.lock 加入 Git 确保团队版本一致
- 版本约束规范：
^1.2.3 = 1.x.x (x≥2.3)~1.2.3 = 1.2.x (x≥3)>=4.5,<5.0
- CI/CD 集成示例：
1
2
3
4
5
6
7
|
# GitHub Actions 配置
- name: Install Poetry
run: pipx install poetry
- name: Install dependencies
run: poetry install --no-interaction
- name: Run tests
run: poetry run pytest
|
💻 10. 工作流示例
graph LR
A[poetry new] --> B[编写代码]
B --> C[poetry add 依赖]
C --> D[poetry run pytest]
D --> E[poetry build]
E --> F[poetry publish]
🔍 11. 学习资源
- 官方文档
- Cheat Sheet：
1
2
3
4
5
6
7
8
|
# 查看已安装包
poetry show
# 更新所有依赖
poetry update
# 导出 requirements.txt
poetry export -f requirements.txt --output requirements.txt
|
提示：结合 uv 加速安装：
poetry export -f requirements.txt | uv pip install -r /dev/stdin