本文是《Python工程化实践》付费专栏第二章讲解如何使用 poetry 实现专业级的 Python 依赖管理。1. 从虚拟环境到依赖管理上一章我们讲了虚拟环境解决了项目之间隔离的问题。但隔离只是第一步。实际开发中你还会遇到这些问题requirements.txt 维护困难—— 手动管理版本容易过时间接依赖不透明。团队成员环境不一致—— 你的机器能跑队友的机器报错pip install 全靠玄学。依赖版本锁定缺失—— 昨天装了个包能跑今天运行就报错因为包作者更新了版本。这些问题的根源在于pip 只管安装不管管理。你需要的是一个能把项目配置、依赖声明、版本锁定、打包发布都统一管理起来的工具。这就是 poetry 要解决的事。2. 为什么选择 poetryPython 生态里依赖管理工具很多poetry 脱颖而出是因为它做到了两件事第一一个文件管所有。poetry 用pyproject.toml同时管理项目元数据、依赖声明、构建配置。不再需要 separate requirements.txt、setup.py、setup.cfg。第二lockfile 锁定精确版本。每次安装依赖poetry 会生成poetry.lock记录每个包及其间接依赖的精确版本。团队成员 CI 环境、本地开发环境完全一致。poetry vs 其他工具对比维度pipuvpoetrypdm依赖声明requirements.txtpyproject.tomlpyproject.tomlpyproject.toml锁定版本❌✅✅✅虚拟环境管理需配合venv✅✅✅打包发布手动✅ (1.0)✅部分学习曲线低低中中2026年流行度高高高中poetry 的定位是一站式项目管理——从开发到打包到发布全流程覆盖。如果你受够了 requirements.txt 的碎片化poetry 是一次性解决方案。3. 安装 poetry3.1 推荐安装方式独立于系统 Python# Windows PowerShell(Invoke-WebRequest-Urihttps://install.python-poetry.org -UseBasicParsing).Content|python -# Linux / macOScurl-sSLhttps://install.python-poetry.org|python3 -这种安装方式的好处是poetry 自己是独立安装的不依赖系统 Python也不污染全局环境。3.2 验证安装poetry--version# 输出类似Poetry (version 2.x.x)注意配置环境变量以及重启终端如果用的是上面的安装方式poetry 二进制文件在Linux/macOS~/.local/bin/Windows%APPDATA%\Python\Scripts\或使用 poetry 自带的 PATH 配置脚本安装程序会自动配置 PATH。如果poetry --version找不到重启终端或手动将上述路径加入 PATH。3.3 配置 poetry# 查看当前配置poetry config--list# 推荐让 poetry 在项目内创建虚拟环境而不是 ~/.cachepoetry config virtualenvs.in-projecttrue这一步很重要。设置后poetry 会在项目根目录下创建.venv和项目文件放在一起方便管理。4. 初始化项目4.1 从零创建项目poetry new myproject这会创建一个标准项目结构myproject/ ├── pyproject.toml ├── README.md ├── src/ │ └── myproject/ │ └── __init__.py └── tests/ └── __init__.py4.2 已有项目接入 poetry如果你已经有项目只需要初始化cdexisting-project poetry initpoetry 会交互式地询问项目名称、版本、描述、作者等信息最后生成pyproject.toml。4.3 指定 Python 版本poetry init--python^3.10这会在pyproject.toml中声明项目需要的 Python 版本范围。队友拿到项目后poetry 会自动检查环境是否符合要求。5. pyproject.toml 核心配置pyproject.toml是 poetry 的核心。把它理解成项目的身份证 依赖清单 构建说明。5.1 基础结构[tool.poetry] name myproject version 0.1.0 description My awesome project authors [Your Name youexample.com] readme README.md packages [{ include src/myproject }] [tool.poetry.dependencies] python ^3.10 requests ^2.28 [tool.poetry.group.dev.dependencies] pytest ^7.0 black ^23.0 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api5.2 依赖版本语法poetry 使用语义化版本SemVer语法含义示例^兼容版本主版本不变^2.282.28 3.0.0~近似版本次版本不变~2.282.28 2.29.0精确版本2.28.0, , , 范围比较2.28 3.0推荐用^既能保证在小版本更新中获得 bug 修复又不会因为大版本升级引入 breaking change。5.3 依赖分组poetry 支持把依赖分组常见的有[tool.poetry.dependencies] # 生产环境必需 requests ^2.28 pydantic ^2.0 [tool.poetry.group.dev.dependencies] # 开发环境工具 pytest ^7.0 black ^23.0 mypy ^1.0 [tool.poetry.group.test.dependencies] # 测试环境额外工具 pytest-cov ^4.0 faker ^18.0好处是团队成员 clone 项目后可以选择只装部分依赖poetryinstall# 安装所有依赖包括 devpoetryinstall--withoutdev# 只装生产依赖poetryinstall--onlydev# 只装开发依赖在 CI/CD 中如果只跑测试可以用poetry install --without dev加速构建。5.4 可选依赖有些包有多个可选的依赖项比如requests可以有security、socks等可选功能[tool.poetry.dependencies] requests { version ^2.28, extras [security] }用户安装时poetry install requests[security]。6. 锁定与安装依赖6.1 安装依赖poetryaddrequests这会做三件事把requests加入pyproject.toml解析依赖树把所有间接依赖也记录下来更新poetry.lock6.2 poetry.lock 的作用不要把 poetry.lock 提交到版本库恰恰相反——一定要提交。poetry.lock记录了每个包的精确版本包括间接依赖。团队成员 CI 环境、本地开发环境通过这个文件保证完全一致。# 团队成员首次 clone 项目poetryinstall这条命令会读取poetry.lock按照锁定版本安装如果 lock 文件不存在poetry 会先解析依赖再生成 lock6.3 更新依赖更新某个包到符合版本约束的最新版本poetry update requests更新所有包poetry update只想看有哪些可以更新poetry show--outdated输出类似requests 2.28.0 2.31.0 ^2.28 HTTP library Django 4.2.0 4.2.4 ^4.2 Web framework6.4 卸载依赖poetry remove requestspoetry 会同时从pyproject.toml和poetry.lock中删除这个包。7. 虚拟环境操作7.1 进入虚拟环境poetry shell这会激活项目对应的虚拟环境终端提示符会显示环境名称。7.2 运行一次性命令不需要每次都激活环境直接用poetry runpoetry run python script.py poetry run pytest poetry run black.7.3 查看环境信息# 查看虚拟环境路径poetryenvinfo# 查看当前安装的所有包poetry show poetry show--tree# 树形显示依赖关系8. 打包与发布8.1 构建包poetry build这会在dist/目录下生成两个文件myproject-0.1.0.tar.gz源码包myproject-0.1.0-py3-none-any.whlWheel 包8.2 发布到 PyPI# 发布到正式 PyPIpoetry publish# 或者先构建再发布poetry buildpoetry publish-y首次发布需要配置 PyPI tokenpoetry config pypi-token.pypi your-token-here发布到 TestPyPI测试用poetry publish--repositorytestpypi8.3 私有包管理公司内部的项目不方便放到 PyPI有几种方案方案一搭建私有 PyPI 服务器可以用pypiserver或购买 Azure Artifacts / GitHub Packages 来托管私有包。# pyproject.toml 中添加私有源 [[tool.poetry.source]] name private url https://your-private-pypi.example.com/simple priority supplemental方案二直接用 git 依赖[tool.poetry.dependencies] my-private-lib { git https://github.com/your-org/private-lib.git, tag v1.0.0 }poetry 支持从 git、githttps、gitssh 等多种方式直接引用依赖。9. 团队协作最佳实践9.1 .gitignore 配置# Poetry 配置 # 注意poetry.lock 不要加入 .gitignore必须提交到版本库 .env # 环境变量 .venv/ # 虚拟环境 venv/ # 构建产物 dist/ build/ *.egg-info/关键点poetry.lock 必须提交到版本库它是团队环境一致性的保证。团队成员 CI 环境、本地开发环境通过 lock 文件保持完全一致。9.2 CI/CD 集成GitHub Actions 示例-name:Install dependenciesrun:poetry install--without dev-name:Run testsrun:poetry run pytest如果 CI 环境不需要开发依赖用--without dev可以节省安装时间。9.3 团队使用规范建议不要手动修改 poetry.lock—— 让 poetry 自己管理更新依赖前先 review——poetry update之前看一下改了什么锁文件提交时机—— 每次poetry add/remove后lock 文件都应该 commit新人 onboarding—— 只需两步git clonepoetry install10. 常见问题与解决方案Q1poetry 和 uv 哪个更好看场景新项目、快速启动、重视性能→ uv快 10-100 倍需要打包发布、团队协作、成熟项目→ poetry功能更全面两者不互斥。实际上很多人用uv 做包管理 poetry 做打包发布因为 poetry 的打包体验比 uv 成熟。Q2poetry install 报错 “The currently activated Python version … is not supported”检查pyproject.toml中的 Python 版本要求[tool.poetry.dependencies] python ^3.10如果你的系统 Python 是 3.9但项目要求 ^3.10poetry 会拒绝安装。可以降低版本要求或者升级系统 Python。Q3lock 文件和 pyproject.toml 冲突了怎么办# 删除 lock 文件让 poetry 重新解析poetry lock --no-update poetryinstall--no-update参数会保留 pyproject.toml 中声明的版本约束只重新解析依赖树。Q4如何同时使用 conda/venv 和 poetry不建议混用。poetry 自己管理虚拟环境不要再用 conda create 或 python -m venv。混用会导致路径冲突。如果已经有 conda 环境可以让 poetry 使用 conda 创建的 Pythonpoetry use python /path/to/conda/pythonQ5安装太慢怎么办poetry 默认从 PyPI 安装国内网络可能较慢。可以配置国内镜像方式一命令行配置全局生效poetry config repositories.pypi https://mirrors.aliyun.com/pypi/simple/方式二pyproject.toml 中配置项目级推荐[[tool.poetry.source]] name aliyun url https://mirrors.aliyun.com/pypi/simple/ default true推荐用方式二配置写在项目文件中团队成员 clone 后自动使用国内镜像无需各自配置。11. 总结poetry 在工程化中的位置依赖管理是 Python 工程化的基石。一个好的依赖管理方案声明式—— 在配置文件中明确写出需要什么而不是靠 pip install 的历史记录可复现—— lockfile 保证任何时间、任何机器都能还原完全相同的环境可协作—— 团队成员 clone 后一条命令就能开始工作可发布—— 一条命令构建包一条命令发布到 PyPIpoetry 同时做到了这四点这就是它成为 2026 年 Python 工程化标配的原因。下一章我们将进入代码质量工具链讲讲如何用ruff一个工具搞定代码格式化、import 排序和静态检查。敬请期待。相关工具对比速查场景推荐工具简单脚本、快速原型pip venv新项目、重视速度uv成熟项目、团队协作、打包发布poetry科学计算环境conda/mamba
Python 依赖管理完全指南：poetry 实战（2026版）
本文是《Python工程化实践》付费专栏第二章讲解如何使用 poetry 实现专业级的 Python 依赖管理。1. 从虚拟环境到依赖管理上一章我们讲了虚拟环境解决了项目之间隔离的问题。但隔离只是第一步。实际开发中你还会遇到这些问题requirements.txt 维护困难—— 手动管理版本容易过时间接依赖不透明。团队成员环境不一致—— 你的机器能跑队友的机器报错pip install 全靠玄学。依赖版本锁定缺失—— 昨天装了个包能跑今天运行就报错因为包作者更新了版本。这些问题的根源在于pip 只管安装不管管理。你需要的是一个能把项目配置、依赖声明、版本锁定、打包发布都统一管理起来的工具。这就是 poetry 要解决的事。2. 为什么选择 poetryPython 生态里依赖管理工具很多poetry 脱颖而出是因为它做到了两件事第一一个文件管所有。poetry 用pyproject.toml同时管理项目元数据、依赖声明、构建配置。不再需要 separate requirements.txt、setup.py、setup.cfg。第二lockfile 锁定精确版本。每次安装依赖poetry 会生成poetry.lock记录每个包及其间接依赖的精确版本。团队成员 CI 环境、本地开发环境完全一致。poetry vs 其他工具对比维度pipuvpoetrypdm依赖声明requirements.txtpyproject.tomlpyproject.tomlpyproject.toml锁定版本❌✅✅✅虚拟环境管理需配合venv✅✅✅打包发布手动✅ (1.0)✅部分学习曲线低低中中2026年流行度高高高中poetry 的定位是一站式项目管理——从开发到打包到发布全流程覆盖。如果你受够了 requirements.txt 的碎片化poetry 是一次性解决方案。3. 安装 poetry3.1 推荐安装方式独立于系统 Python# Windows PowerShell(Invoke-WebRequest-Urihttps://install.python-poetry.org -UseBasicParsing).Content|python -# Linux / macOScurl-sSLhttps://install.python-poetry.org|python3 -这种安装方式的好处是poetry 自己是独立安装的不依赖系统 Python也不污染全局环境。3.2 验证安装poetry--version# 输出类似Poetry (version 2.x.x)注意配置环境变量以及重启终端如果用的是上面的安装方式poetry 二进制文件在Linux/macOS~/.local/bin/Windows%APPDATA%\Python\Scripts\或使用 poetry 自带的 PATH 配置脚本安装程序会自动配置 PATH。如果poetry --version找不到重启终端或手动将上述路径加入 PATH。3.3 配置 poetry# 查看当前配置poetry config--list# 推荐让 poetry 在项目内创建虚拟环境而不是 ~/.cachepoetry config virtualenvs.in-projecttrue这一步很重要。设置后poetry 会在项目根目录下创建.venv和项目文件放在一起方便管理。4. 初始化项目4.1 从零创建项目poetry new myproject这会创建一个标准项目结构myproject/ ├── pyproject.toml ├── README.md ├── src/ │ └── myproject/ │ └── __init__.py └── tests/ └── __init__.py4.2 已有项目接入 poetry如果你已经有项目只需要初始化cdexisting-project poetry initpoetry 会交互式地询问项目名称、版本、描述、作者等信息最后生成pyproject.toml。4.3 指定 Python 版本poetry init--python^3.10这会在pyproject.toml中声明项目需要的 Python 版本范围。队友拿到项目后poetry 会自动检查环境是否符合要求。5. pyproject.toml 核心配置pyproject.toml是 poetry 的核心。把它理解成项目的身份证 依赖清单 构建说明。5.1 基础结构[tool.poetry] name myproject version 0.1.0 description My awesome project authors [Your Name youexample.com] readme README.md packages [{ include src/myproject }] [tool.poetry.dependencies] python ^3.10 requests ^2.28 [tool.poetry.group.dev.dependencies] pytest ^7.0 black ^23.0 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api5.2 依赖版本语法poetry 使用语义化版本SemVer语法含义示例^兼容版本主版本不变^2.282.28 3.0.0~近似版本次版本不变~2.282.28 2.29.0精确版本2.28.0, , , 范围比较2.28 3.0推荐用^既能保证在小版本更新中获得 bug 修复又不会因为大版本升级引入 breaking change。5.3 依赖分组poetry 支持把依赖分组常见的有[tool.poetry.dependencies] # 生产环境必需 requests ^2.28 pydantic ^2.0 [tool.poetry.group.dev.dependencies] # 开发环境工具 pytest ^7.0 black ^23.0 mypy ^1.0 [tool.poetry.group.test.dependencies] # 测试环境额外工具 pytest-cov ^4.0 faker ^18.0好处是团队成员 clone 项目后可以选择只装部分依赖poetryinstall# 安装所有依赖包括 devpoetryinstall--withoutdev# 只装生产依赖poetryinstall--onlydev# 只装开发依赖在 CI/CD 中如果只跑测试可以用poetry install --without dev加速构建。5.4 可选依赖有些包有多个可选的依赖项比如requests可以有security、socks等可选功能[tool.poetry.dependencies] requests { version ^2.28, extras [security] }用户安装时poetry install requests[security]。6. 锁定与安装依赖6.1 安装依赖poetryaddrequests这会做三件事把requests加入pyproject.toml解析依赖树把所有间接依赖也记录下来更新poetry.lock6.2 poetry.lock 的作用不要把 poetry.lock 提交到版本库恰恰相反——一定要提交。poetry.lock记录了每个包的精确版本包括间接依赖。团队成员 CI 环境、本地开发环境通过这个文件保证完全一致。# 团队成员首次 clone 项目poetryinstall这条命令会读取poetry.lock按照锁定版本安装如果 lock 文件不存在poetry 会先解析依赖再生成 lock6.3 更新依赖更新某个包到符合版本约束的最新版本poetry update requests更新所有包poetry update只想看有哪些可以更新poetry show--outdated输出类似requests 2.28.0 2.31.0 ^2.28 HTTP library Django 4.2.0 4.2.4 ^4.2 Web framework6.4 卸载依赖poetry remove requestspoetry 会同时从pyproject.toml和poetry.lock中删除这个包。7. 虚拟环境操作7.1 进入虚拟环境poetry shell这会激活项目对应的虚拟环境终端提示符会显示环境名称。7.2 运行一次性命令不需要每次都激活环境直接用poetry runpoetry run python script.py poetry run pytest poetry run black.7.3 查看环境信息# 查看虚拟环境路径poetryenvinfo# 查看当前安装的所有包poetry show poetry show--tree# 树形显示依赖关系8. 打包与发布8.1 构建包poetry build这会在dist/目录下生成两个文件myproject-0.1.0.tar.gz源码包myproject-0.1.0-py3-none-any.whlWheel 包8.2 发布到 PyPI# 发布到正式 PyPIpoetry publish# 或者先构建再发布poetry buildpoetry publish-y首次发布需要配置 PyPI tokenpoetry config pypi-token.pypi your-token-here发布到 TestPyPI测试用poetry publish--repositorytestpypi8.3 私有包管理公司内部的项目不方便放到 PyPI有几种方案方案一搭建私有 PyPI 服务器可以用pypiserver或购买 Azure Artifacts / GitHub Packages 来托管私有包。# pyproject.toml 中添加私有源 [[tool.poetry.source]] name private url https://your-private-pypi.example.com/simple priority supplemental方案二直接用 git 依赖[tool.poetry.dependencies] my-private-lib { git https://github.com/your-org/private-lib.git, tag v1.0.0 }poetry 支持从 git、githttps、gitssh 等多种方式直接引用依赖。9. 团队协作最佳实践9.1 .gitignore 配置# Poetry 配置 # 注意poetry.lock 不要加入 .gitignore必须提交到版本库 .env # 环境变量 .venv/ # 虚拟环境 venv/ # 构建产物 dist/ build/ *.egg-info/关键点poetry.lock 必须提交到版本库它是团队环境一致性的保证。团队成员 CI 环境、本地开发环境通过 lock 文件保持完全一致。9.2 CI/CD 集成GitHub Actions 示例-name:Install dependenciesrun:poetry install--without dev-name:Run testsrun:poetry run pytest如果 CI 环境不需要开发依赖用--without dev可以节省安装时间。9.3 团队使用规范建议不要手动修改 poetry.lock—— 让 poetry 自己管理更新依赖前先 review——poetry update之前看一下改了什么锁文件提交时机—— 每次poetry add/remove后lock 文件都应该 commit新人 onboarding—— 只需两步git clonepoetry install10. 常见问题与解决方案Q1poetry 和 uv 哪个更好看场景新项目、快速启动、重视性能→ uv快 10-100 倍需要打包发布、团队协作、成熟项目→ poetry功能更全面两者不互斥。实际上很多人用uv 做包管理 poetry 做打包发布因为 poetry 的打包体验比 uv 成熟。Q2poetry install 报错 “The currently activated Python version … is not supported”检查pyproject.toml中的 Python 版本要求[tool.poetry.dependencies] python ^3.10如果你的系统 Python 是 3.9但项目要求 ^3.10poetry 会拒绝安装。可以降低版本要求或者升级系统 Python。Q3lock 文件和 pyproject.toml 冲突了怎么办# 删除 lock 文件让 poetry 重新解析poetry lock --no-update poetryinstall--no-update参数会保留 pyproject.toml 中声明的版本约束只重新解析依赖树。Q4如何同时使用 conda/venv 和 poetry不建议混用。poetry 自己管理虚拟环境不要再用 conda create 或 python -m venv。混用会导致路径冲突。如果已经有 conda 环境可以让 poetry 使用 conda 创建的 Pythonpoetry use python /path/to/conda/pythonQ5安装太慢怎么办poetry 默认从 PyPI 安装国内网络可能较慢。可以配置国内镜像方式一命令行配置全局生效poetry config repositories.pypi https://mirrors.aliyun.com/pypi/simple/方式二pyproject.toml 中配置项目级推荐[[tool.poetry.source]] name aliyun url https://mirrors.aliyun.com/pypi/simple/ default true推荐用方式二配置写在项目文件中团队成员 clone 后自动使用国内镜像无需各自配置。11. 总结poetry 在工程化中的位置依赖管理是 Python 工程化的基石。一个好的依赖管理方案声明式—— 在配置文件中明确写出需要什么而不是靠 pip install 的历史记录可复现—— lockfile 保证任何时间、任何机器都能还原完全相同的环境可协作—— 团队成员 clone 后一条命令就能开始工作可发布—— 一条命令构建包一条命令发布到 PyPIpoetry 同时做到了这四点这就是它成为 2026 年 Python 工程化标配的原因。下一章我们将进入代码质量工具链讲讲如何用ruff一个工具搞定代码格式化、import 排序和静态检查。敬请期待。相关工具对比速查场景推荐工具简单脚本、快速原型pip venv新项目、重视速度uv成熟项目、团队协作、打包发布poetry科学计算环境conda/mamba
