Python Poetry #

概述 #

Poetry 是一个现代化的 Python 依赖管理和打包工具，它解决了传统 pip 和 virtualenv 组合的诸多痛点。Poetry 提供了统一的工具链，可以处理依赖管理、虚拟环境、包发布等所有任务。

主要特性 #

  • 依赖解析：智能解决依赖冲突
  • 虚拟环境管理：自动创建和管理虚拟环境
  • 依赖锁定：生成可复现的依赖锁文件
  • 包发布：轻松发布到 PyPI
  • 项目脚手架：快速创建新项目结构
  • 配置简单：使用 pyproject.toml 统一配置

安装 Poetry #

官方推荐安装方式 #

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

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

使用 pip 安装（不推荐） #

bash 
pip install --user poetry

验证安装 #

bash 
poetry --version

基本使用 #

创建新项目 #

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

# 创建带有特定包名的项目
poetry new my-project --name "my_package"

# 创建 src 布局的项目
poetry new my-project --src

初始化现有项目 #

bash 
# 在现有目录中初始化
cd existing-project
poetry init

初始化过程会交互式地询问项目信息：

  • 包名
  • 版本号
  • 描述
  • 作者
  • 许可证
  • 依赖项

项目结构 #

典型的 Poetry 项目结构：

text 
my-project/
├── pyproject.toml
├── poetry.lock
├── README.md
├── my_package/
│   └── __init__.py
└── tests/
    └── __init__.py

依赖管理 #

添加依赖 #

bash 
# 添加生产依赖
poetry add requests

# 添加开发依赖
poetry add --dev pytest
poetry add -D pytest  # 简写

# 添加特定版本
poetry add django==4.2.0

# 添加版本范围
poetry add "flask>=2.0,<3.0"

# 添加 Git 依赖
poetry add git+https://github.com/username/repo.git

# 添加本地路径依赖
poetry add ./local-package

查看依赖 #

bash 
# 查看已安装的包
poetry show

# 查看特定包信息
poetry show requests

# 查看依赖树
poetry show --tree

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

# 查看最新的包版本
poetry show --latest

更新依赖 #

bash 
# 更新所有依赖到最新兼容版本
poetry update

# 更新特定依赖
poetry update requests

# 更新到最新版本（可能破坏兼容性）
poetry add package@latest

移除依赖 #

bash 
# 移除依赖
poetry remove requests

# 移除开发依赖
poetry remove --dev pytest

虚拟环境管理 #

进入虚拟环境 #

bash 
# 激活虚拟环境
poetry shell

# 在虚拟环境中执行单个命令
poetry run python script.py
poetry run pytest

虚拟环境信息 #

bash 
# 查看虚拟环境路径
poetry env info

# 查看虚拟环境 Python 路径
poetry env info --path

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

# 删除虚拟环境
poetry env remove python

配置虚拟环境 #

bash 
# 在项目目录内创建虚拟环境
poetry config virtualenvs.in-project true

# 设置虚拟环境路径
poetry config virtualenvs.path /path/to/venvs

项目配置 (pyproject.toml) #

Poetry 使用 pyproject.toml 文件来管理项目配置：

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

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"
click = "^8.1.0"

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

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

版本约束语法 #

  • ^1.2.3：兼容版本（>=1.2.3, <2.0.0）
  • ~1.2.3：近似版本（>=1.2.3, <1.3.0）
  • >=1.2.3：大于等于指定版本
  • <=1.2.3：小于等于指定版本
  • ==1.2.3：精确版本
  • *：任何版本

脚本和命令 #

定义脚本 #

在 pyproject.toml 中定义脚本：

toml 
[tool.poetry.scripts]
my-script = "my_package.cli:main"

运行脚本 #

bash 
# 运行定义的脚本
poetry run my-script

# 运行 Python 模块
poetry run python -m my_package

构建和发布 #

构建项目 #

bash 
# 构建包
poetry build

# 构建源码包
poetry build --format sdist

# 构建 wheel 包
poetry build --format wheel

发布到 PyPI #

bash 
# 配置 PyPI 令牌
poetry config pypi-token.pypi your-token

# 发布到 PyPI
poetry publish

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

本地安装 #

bash 
# 在开发模式下安装
poetry install

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

# 同步依赖（移除不需要的包）
poetry install --sync

高级功能 #

插件系统 #

Poetry 支持插件扩展功能：

bash 
# 安装插件
poetry self add poetry-plugin

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

依赖组 #

管理不同类型的依赖组：

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

[tool.poetry.group.docs.dependencies]
sphinx = "^5.0.0"

[tool.poetry.group.test.dependencies]
pytest-cov = "^4.0.0"

安装特定组的依赖：

bash 
poetry install --with docs,test

环境变量配置 #

bash 
# 设置镜像源（国内用户）
poetry config repositories.custom https://pypi.tuna.tsinghua.edu.cn/simple/

# 设置缓存目录
poetry config cache-dir /custom/cache/path

最佳实践 #

1. 版本控制 #

  • 将 poetry.lock 文件加入版本控制
  • 不要手动编辑 poetry.lock 文件
  • 定期更新依赖以获取安全修复

2. 开发流程 #

bash 
# 开发新功能时
poetry add new-dependency
poetry run pytest  # 运行测试
poetry build  # 构建包

# 协作开发时
git clone project
poetry install  # 安装一致的依赖

3. 生产部署 #

bash 
# 生产环境安装
poetry install --no-dev --no-root

# 或者使用 pip 安装（如果 Poetry 不可用）
pip install --no-deps dist/*.whl
pip install -r <(poetry export -f requirements.txt)

4. 依赖导出 #

bash 
# 导出为 requirements.txt
poetry export -f requirements.txt --output requirements.txt

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

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

常见问题解决 #

依赖冲突 #

bash 
# 查看依赖冲突详情
poetry show --tree

# 尝试更新解决冲突
poetry update

# 手动指定兼容版本
poetry add "package>=1.0,<2.0"

虚拟环境问题 #

bash 
# 重新创建虚拟环境
poetry env remove python
poetry install

# 强制重新安装依赖
poetry install --no-cache

性能优化 #

bash 
# 使用国内镜像源
poetry source add --priority=primary tuna https://pypi.tuna.tsinghua.edu.cn/simple/

# 禁用并行安装（解决网络问题）
poetry install --no-parallel

与其他工具比较 #

特性 Poetry pip + virtualenv Pipenv
依赖解析 ✅ 优秀 ❌ 基本 ✅ 良好
虚拟环境 ✅ 自动 ❌ 手动 ✅ 自动
依赖锁定 ✅ 强 ❌ 弱 ✅ 强
包发布 ✅ 内置 ❌ 需要额外工具 ❌ 需要额外工具
配置格式 ✅ TOML ❌ 多种格式 ✅ TOML
学习曲线 ⚠️ 中等 ✅ 简单 ⚠️ 中等

总结 #

Poetry 是现代 Python 开发的理想选择，它提供了完整的依赖管理和项目打包解决方案。通过统一的配置文件和强大的命令行工具，Poetry 大大简化了 Python 项目的开发、测试和部署流程。

推荐使用场景 #

  • 新项目开发
  • 需要严格依赖管理的项目
  • 需要发布到 PyPI 的包
  • 团队协作开发
  • 需要可复现构建的项目

学习资源 #

最后更新：2026-02-07