Poetry 是 Python 的现代化包管理与项目构建工具，目标是统一项目依赖管理、虚拟环境管理与打包发布流程。

它解决了传统 Python 项目中常见的几个痛点：

• pip + requirements.txt 依赖管理混乱、不易锁定版本；
• virtualenv 虚拟环境管理与依赖管理分离；
• setup.py 打包发布过程复杂；
• 不支持声明式的依赖配置。

一句话总结：
Poetry 是一个集 包依赖管理 + 虚拟环境管理 + 构建与发布 于一体的工具。

---

二、Poetry 的核心特性

功能	说明
📦 统一依赖管理	通过 pyproject.toml 声明依赖，自动生成锁文件 poetry.lock，确保依赖可重现性。
🧩 自动虚拟环境	自动创建并管理独立的虚拟环境，无需手动 venv 或 virtualenv。
🚀 项目构建与发布	一条命令即可构建并发布到 PyPI 或私有仓库。
🔐 精确锁定版本	使用 poetry.lock 精确记录依赖的版本与来源，避免“works on my machine”。
🔧 声明式配置	使用 pyproject.toml（PEP 518/621 标准）统一项目元数据与依赖信息。

---

三、Poetry vs pip + virtualenv

对比项	pip + virtualenv	Poetry
依赖声明	requirements.txt	pyproject.toml
依赖锁定	手动	自动生成 poetry.lock
虚拟环境	需手动创建与激活	自动创建与管理
构建发布	需编写 setup.py	poetry build + poetry publish
版本冲突处理	手动调试	内置版本解析器自动解决
可重现环境	弱	强（依赖锁定）

---

四、Poetry 安装

推荐使用官方安装脚本：

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

安装后可检查版本：

poetry --version

安装路径通常位于 ~/.local/bin/poetry（Linux/Mac）或 %APPDATA%\pypoetry（Windows）。

---

五、Poetry 项目结构

创建新项目：

poetry new myproject

生成的目录结构如下：

myproject/
├── pyproject.toml        # 项目配置文件
├── poetry.lock           # 依赖锁定文件（首次 install 后生成）
├── myproject/            # 包代码
│   └── __init__.py
└── tests/                # 测试代码

---

六、依赖管理命令

1. 添加依赖

poetry add requests

添加开发依赖：

poetry add --dev pytest black

自动更新 pyproject.toml 和 poetry.lock。

2. 安装依赖

poetry install

安装指定环境下的依赖（例如生产）：

poetry install --without dev

3. 移除依赖

poetry remove requests

4. 更新依赖

poetry update

5. 查看依赖树

poetry show --tree

---

七、虚拟环境管理

Poetry 自动为每个项目创建独立虚拟环境。
常用命令如下：

命令	说明
poetry env list	列出虚拟环境
poetry env info	显示当前虚拟环境信息
poetry shell	激活虚拟环境
poetry run python	在虚拟环境中执行命令（不进入 shell）

例如：

poetry run pytest

---

八、构建与发布

构建包

poetry build

生成：

dist/
├── myproject-0.1.0.tar.gz
└── myproject-0.1.0-py3-none-any.whl

发布到 PyPI

poetry publish --build --username <user> --password <pass>

或使用 token：

poetry config pypi-token.pypi <your-token>
poetry publish --build

---

九、配置文件详解：pyproject.toml

示例：

[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "A simple example project"
authors = ["Alice <alice@example.com>"]
readme = "README.md"
license = "MIT"

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"

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

---

十、Poetry 常用工作流示例

# 初始化项目
poetry init

# 添加依赖
poetry add fastapi uvicorn

# 激活环境
poetry shell

# 启动服务
poetry run uvicorn app.main:app --reload

# 生成锁文件并安装依赖
poetry install

# 构建并发布包
poetry build && poetry publish

---

十一、与其他工具集成

• ✅ 支持 PyCharm / VS Code 自动识别 Poetry 虚拟环境；
• ✅ 可与 Docker 集成（可直接复制 .venv 或使用 poetry export 导出 requirements.txt）；
• ✅ 支持 多环境依赖管理（dev/test/prod）。

---

十二、实用技巧

场景	命令
导出为 requirements.txt	poetry export -f requirements.txt --output requirements.txt
强制重新创建虚拟环境	poetry env remove python && poetry install
仅更新某个包	poetry update requests
检查安全漏洞	poetry check

---

✅ 总结

优点	缺点
统一依赖、环境、构建管理	首次学习曲线略高
更安全的依赖锁定机制	与某些旧版工具兼容性差
简化包发布流程	CI/CD 集成需额外配置
自动虚拟环境、可重现性强	需适应新语法（pyproject.toml）