Poetry Python 依赖管理¶

Poetry 是 Python 项目依赖管理和打包工具，用 pyproject.toml 管理所有配置，自动解析依赖冲突并生成锁文件，是除 uv 外最成熟的 Python 项目管理方案。

核心知识点¶

知识点	说明
工具定位	Python 依赖管理 + 项目打包 + 虚拟环境管理
最新版本	v1.8+
核心优势	依赖解析准确、锁文件保证可重复、打包发布一体
配置文件	pyproject.toml（统一配置）
替代方案	uv（更快）、pip + requirements.txt（更简单）

安装配置¶

# 官方安装方式
curl -sSL https://install.python-poetry.org | python3 -  # 安装
poetry --version                                          # 验证

# 或用 pip
pip install poetry

# 或用 uv
uv tool install poetry

基本使用¶

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

# 或在已有目录初始化
poetry init                            # 交互式初始化

# 依赖管理
poetry add pandas numpy                # 添加依赖
poetry add pytest --group dev          # 添加到开发组
poetry remove pandas                   # 移除依赖
poetry update                          # 更新依赖

# 环境管理
poetry install                         # 安装所有依赖
poetry shell                           # 激活虚拟环境
poetry run python script.py            # 在虚拟环境中运行

# 打包发布
poetry build                           # 构建包（wheel + sdist）
poetry publish                         # 发布到 PyPI

pyproject.toml 示例¶

[tool.poetry]
name = "metagenome-analysis"
version = "0.1.0"
description = "宏基因组分析工具"
authors = ["Your Name <email@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"
pandas = "^2.0"
numpy = "^1.24"
scikit-learn = "^1.3"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
ruff = "^0.4"

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

常见报错与解决¶

报错信息	原因	解决方法
`SolverProblemError`	依赖冲突	放宽版本约束或检查冲突包
`No module named`	未在 Poetry 环境中运行	用 `poetry run` 或 `poetry shell`
安装太慢	依赖解析耗时	考虑用 uv 替代

速查表¶

# ===== Poetry 速查表 =====

poetry new project            # 创建项目
poetry add pandas             # 添加依赖
poetry add pytest --group dev # 开发依赖
poetry remove pkg             # 移除
poetry install                # 安装
poetry update                 # 更新
poetry run python script.py   # 运行
poetry shell                  # 进入环境
poetry build                  # 构建包
poetry publish                # 发布

# Poetry vs uv
# Poetry: 成熟稳定，生态完善
# uv: 速度快 10-100 倍，功能追赶中
# 新项目推荐用 uv，老项目可继续用 Poetry