当前位置： 首页 > news >正文

poetry

news 2025/8/14 15:24:49

Poetry 是一个更现代、更强大的 Python 包和依赖管理工具，它不仅能安装依赖，还能帮你创建项目、管理虚拟环境、打包发布、锁定依赖版本等。

🌟 Poetry 的核心优势

功能传统 pip + requirements.txtPoetry
依赖安装✅✅
依赖锁定（精确版本）❌（需 pip freeze > ...）✅（自动生成 poetry.lock）
虚拟环境管理❌（需手动）✅（自动创建/管理）
添加/删除依赖手动编辑文件命令行一键操作
发布包到 PyPI需额外工具内置支持
多环境支持（dev/test）需多个文件支持分组依赖

一、安装 Poetry

下载安装的过程，主要是对于安装路径，有2种方式：

第一种：

1. 下载 poetry 
curl -sSL https://install.python-poetry.org | python3.9 -

这里注意官方命令中是给的这样的：

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

注意，命令里 python3，就是你环境里安装的 python，因为，好吧，linux安装python且，希望可以使用 ssl 是个有点麻烦的事，因此我在有了 python3.9 之后，在搞 python3.10 的时候就没有再配置ssl，这样以来，就需要看你的 python3 是指向 3.9 还是 3.10，因为我本地是 3.9 可用 ssl，所以，官方的下载命令，稍作修饰即可。

当然，这里的安装路径为：

  • 默认安装路径为：~/.local/share/pypoetry/venv
  • 可执行文件路径为：~/.local/bin/poetry
2. 将 poetry 添加到 PATH

如果不执行这个动作，那么，换个窗口，poetry 就用不了了。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

第二种：

🔹 指定目录安装步骤
1. 设置自定义安装目录（如 /opt/poetry）

export POETRY_HOME="/opt/poetry"

注意：你需要有写入 /opt/poetry 的权限，可以使用 sudo 或修改目录权限。

2. 安装 Poetry 到指定目录

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

安装路径变为：/opt/poetry/venv
可执行文件路径为：/opt/poetry/bin/poetry

3. 将 poetry 添加到 PATH

echo 'export POETRY_HOME="/opt/poetry"' >> ~/.bashrc
echo 'export PATH="$POETRY_HOME/bin:$PATH"' >> ~/.bashrc

4. 设置镜像源（可选）

export POETRY_PYPI_MIRROR="https://pypi.tuna.tsinghua.edu.cn/simple"

5. 永久生效（直接执行以下命令，写入 shell 配置）

echo 'export POETRY_HOME="/opt/poetry"' >> ~/.bashrc
echo 'export PATH="$POETRY_HOME/bin:$PATH"' >> ~/.bashrc
echo 'export POETRY_PYPI_MIRROR="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
source ~/.bashrc

此处参考：Poetry 在 Linux 和 Windows 系统中的安装步骤_poetry安装-CSDN博客

二、创建新项目

poetry new my_project

然后，结果，大概长这样：

三.管理虚拟环境

这个时候，执行：

poetry env list

看下有没有虚拟环境

其结果为空。

然后我们就可以创建虚拟环境了：

poetry env use python3.10

注意， poetry 可以对同一个项目管理多个虚拟环境。

可以来回切环境：

poetry 默认会将虚拟环境统一放在指定目录，即 C:\Users\xxx\AppData\Local\pypoetry\Cache\virtualenvs\。虚拟环境的命名规则为项目名-随机数-python版本。我们可以通过修改配置，将虚拟环境创建到我们的项目里：

poetry config --list

将virtualenvs.in-project设置为true即可：

poetry config virtualenvs.in-project true

另外，我们可以通过命令查看当前的虚拟环境：

poetry env info

进入虚拟环境：

poetry shell

退出虚拟环境变量的命令为：

exit

注意，这个命令，在 poetry 2.0.0 以后被弃用了

所以，2.0 之后，它更推荐直接使用 run

poetry run xxx
poetry run 能运行什么？任何安装在项目中的命令：python, black, mypy, sphinx-build 等
是否必须用？✅ 是的，这是标准做法

🎯 最佳实践：

  • 开发时：用 poetry run pytest 运行测试
  • CI/CD 中：用 poetry install + poetry run pytest 构建可靠流水线

这样可以确保无论谁在什么机器上运行，环境都是一致的。

四.使用

poetry 是通过 add 来添加第三方库的。

poetry add flask

这个时候，可以发现，我们的项目里，多了一个 .lock 文件。

也就是说，当 add 的时候，poetry 会更新 poetry.lock 和 pyproject.toml 文件。

另外扯一句：

pyproject.toml 是一个用于 Python 项目配置的标准化文件，自 PEP 518 起被引入，旨在统一和简化 Python 项目的构建系统和元数据管理。它逐渐取代了传统的 setup.py 和 setup.cfg 文件。

这个文件使用 TOML（Tom's Obvious, Minimal Language）格式，可以包含项目元数据、依赖项、构建配置以及各种开发工具的设置。

poetry.lock文件：

它是由 poetry 根据 pyproject.toml 文件，自动生成的。

  • poetry.lock 文件记录了每个依赖的精确版本和哈希值。
  • 团队协作时，提交 poetry.lock 到 Git。
  • 其他人运行 poetry install 就能得到完全一致的环境。

poetry 不仅可以 add 安装第三方应用，它也可以安装 whl 文件：

pip是可以直接安装whl文件的，如何通过poetry安装whl文件呢？Poetry 主要用于管理项目依赖和构建，而不像 pip 那样直接安装 .whl 文件。不过，Poetry 可间接地通过 pyproject.toml 文件指定依赖来安装 .whl 文件。如果已经有一个 .whl 文件，并且希望使用 Poetry 安装它，可以通过以下步骤来实现：

（1） 创建或更新 pyproject.toml

在项目的 pyproject.toml 文件中添加对本地 .whl 文件的依赖。假设 .whl 文件路径是 ./dist/poetry_demo-0.1.0-py3-none-any.whl，pyproject.toml 文件可像这样配置：

[tool.poetry]
name = "example-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"][tool.poetry.dependencies]
python = "^3.10"
poetry-demo = { path = "./dist/poetry_demo-0.1.0-py3-none-any.whl" }[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

以下是整理好的 Poetry 常用命令、功能及示例表格：

命令功能示例
poetry add添加依赖到项目poetry add requests
poetry remove从项目中移除依赖poetry remove requests
poetry export导出依赖到其它格式文件poetry export -f requirements.txt
poetry env use指定项目使用的 Python 解释器poetry env use python3.8
poetry show显示项目依赖的详细信息poetry show requests
poetry init初始化一个新项目并生成 pyproject.tomlpoetry init
poetry install安装项目依赖poetry install
poetry new创建一个新的 Poetry 项目poetry new my_project
poetry build打包项目，通常在 dist 目录poetry build
poetry publish发布项目到 PyPIpoetry publish --username <your-username> --password <your-password>

在 Poetry 中添加多个依赖组（如 dev、test、doc、lint 等）是非常常见的做法，可以让你更精细地管理不同用途的依赖。

Poetry 使用 --group 参数来指定依赖属于哪个组。以下是详细的使用方法：

✅ 方法一：命令行添加（推荐）

1. 添加一个新组并安装依赖

# 添加测试依赖组
poetry add pytest pytest-cov --group test# 添加文档依赖组
poetry add sphinx sphinx-rtd-theme --group doc# 添加代码质量依赖组
poetry add black flake8 isort --group lint# 添加类型检查组
poetry add mypy --group typecheck

✅ 这些命令会自动在 pyproject.toml 中创建对应的组，并安装包。

2. 查看已安装的组

poetry show --tree
my-package
├── pytest
│   └── ... 
└── black└── ...

或者查看所有组：

poetry show --only test
poetry show --only lint

安装特定组的依赖

# 安装主依赖 + 所有可选组
poetry install# 只安装主依赖
poetry install --only main# 安装主依赖 + 某个组
poetry install --with test
poetry install --with lint,doc# 安装主依赖 + 所有可选组
poetry install --with dev,test,lint,doc# 安装除了某个组之外的所有依赖
poetry install --without lint

🌐 实际项目中的常见分组建议

# 开发时安装所有工具
poetry install --with dev,test,lint,doc# CI/CD 测试环境
poetry install --only main
poetry install --with test
poetry run pytest# 生成文档
poetry install --with doc
poetry run sphinx-build -b html docs docs/_build

🧩 小技巧：创建别名组（如 dev 包含多个子组）

虽然 Poetry 不直接支持“组的组”，但你可以用脚本或 Makefile 简化操作：

# Makefile
dev:poetry install --with test,lint,doc,typechecktest:poetry install --with testpoetry run pytestlint:poetry install --with lintpoetry run black . && poetry run flake8

然后使用：

make dev    # 安装所有开发依赖
make test   # 运行测试

✅ 总结

目标命令
添加新组依赖poetry add pkg --group 组名
安装某个组poetry install --with 组名
安装多个组poetry install --with lint,test,doc
手动定义组编辑 pyproject.toml 的 [tool.poetry.group.xxx]

🎯 建议：合理使用分组可以让项目更清晰，比如：

  • main：核心依赖（自动安装）
  • test：测试框架
  • lint：代码格式化
  • doc：文档生成
  • typecheck：类型检查
  • dev：开发工具总和（可通过脚本组合）

注意啊：正常来说，我们 add 的时候，就把改下的都下了，不需要额外的去 install 。

当你运行：

poetry add some-package

Poetry 会自动完成以下几步：

  1. 下载并安装这个包到当前虚拟环境中 ✅
  2. 添加依赖到 pyproject.toml 中 ✅
  3. 更新 poetry.lock 文件（锁定版本） ✅

所以，poetry add 之后包已经可以立即使用了，不需要再运行 poetry install。

🆚 对比：什么情况下需要 poetry install？

场景是否需要 poetry install说明
poetry add requests❌ 不需要add 已经安装了
poetry remove requests❌ 不需要remove 也会立即生效
从 Git 克隆项目后✅ 需要第一次安装所有依赖
修改了 pyproject.toml 但没用 add/remove✅ 建议运行确保 lock 文件和环境同步
想更新所有依赖到最新兼容版本✅ 用 poetry update相当于 pip install --upgrade

🧪 举个例子

# 1. 添加 requests 包
poetry add requests# ✅ 此时 requests 已安装，可以直接运行
poetry run python -c "import requests; print(requests.__version__)"# 2. 不需要再执行 install
# poetry install  ← 这一步是多余的

🔁 什么时候建议运行 poetry install？

虽然 add 后不需要，但在这些情况下建议运行：

# 1. 团队协作：别人克隆了你的项目
git clone my-project
cd my-project
poetry install  # 安装所有依赖（包括 lock 文件锁定的版本）# 2. 你手动编辑了 pyproject.toml（没用 add）
# 然后运行：
poetry install  # 确保 lock 文件更新并安装# 3. 确保环境完全同步
poetry install --sync  # 移除 lock 文件中没有的包（更严格）

✅ 总结

命令是否自动安装？是否需要再 run install？
poetry add pkg✅ 是❌ 否
poetry remove pkg✅ 是❌ 否
git clone + 首次进入❌ 否✅ 是
手动修改 pyproject.toml❌ 否✅ 建议是

🎯 最佳实践：

  • 用 poetry add/remove 管理依赖 → 自动安装，无需 install
  • 克隆项目或 CI/CD 中 → 一定要 poetry install

这样既高效又安全 💪

另外，对于 poetry init 命令的使用场景：

从 requirements.txt 迁移到 Poetry

  1. 删除 requirements.txt（可选）
  2. 在项目根目录运行：
poetry init
  1. 手动添加依赖：
# 例如从 requirements.txt 读取
cat requirements.txt | xargs poetry add

或逐个添加：

poetry add django flask requests

✅ 总结：Poetry vs pip + requirements.txt

场景推荐方式
新项目✅ 强烈推荐使用 Poetry
老项目可逐步迁移，先用 poetry init 接管
团队协作Poetry + poetry.lock 更可靠
发布包Poetry 更方便

所以，它的应用，主要是针对老项目用的。

(myvenv) ymk@ubuntu:~/ymk_django_test/django_rq_model_test$ poetry init
/home/ymk/.local/share/pypoetry/venv/lib/python3.9/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 3.0.2'. See: https://github.com/urllib3/urllib3/issues/3020warnings.warn(This command will guide you through creating your pyproject.toml config.Package name [django_rq_model_test]:  django_rq_model_test
Version [0.1.0]:  
Description []:  
Author [None, n to skip]:  
normalize() argument 2 must be str, not None
Author [None, n to skip]:  ymk
License []:  
Compatible Python versions [>=3.8]:  Would you like to define your main dependencies interactively? (yes/no) [yes] You can specify a package in the following forms:- A single name (requests): this will search for matches on PyPI- A name and a constraint (requests@^2.23.0)- A git url (git+https://github.com/python-poetry/poetry.git)- A git url with a revision         (git+https://github.com/python-poetry/poetry.git#develop)- A file path (../my-package/my-package.whl)- A directory (../my-package/)- A url (https://example.com/packages/my-package-0.1.0.tar.gz)Package to add or search for (leave blank to skip): addUnable to find packageAdd a package (leave blank to skip): 
Would you like to define your development dependencies interactively? (yes/no) [yes] 
Package to add or search for (leave blank to skip): add
Unable to find packageAdd a package (leave blank to skip): add
Unable to find packageAdd a package (leave blank to skip): Generated file[project]
name = "django-rq-model-test"
version = "0.1.0"
description = ""
authors = [{name = "ymk"}
]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
][build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"Do you confirm generation? (yes/no) [yes] 
(myvenv) ymk@ubuntu:~/ymk_django_test/django_rq_model_test$

这是一个老项目直接使用 poetry init  说实话，不好用。

它生成的文件长这样：

所以，我个人觉得，对于老项目，最好别用 init，老项目一般都有 requirement.txt ，我觉的，从requirement.txt 转到 poetry 比较靠谱。

========================

🔍 详细解释：poetry install 到底怎么工作？

1. 它优先使用 poetry.lock 文件

当你运行：

poetry install

Poetry 会：

  1. 先检查是否存在 poetry.lock 文件

    • 如果存在 → 严格按照 poetry.lock 中记录的版本安装
    • 每个包的精确版本、来源、哈希值都来自 .lock 文件
    • ✅ 确保你和团队成员、CI/CD、生产环境安装的依赖完全一致

  2. 如果 poetry.lock 不存在

    • Poetry 会根据 pyproject.toml 中的依赖声明（如 requests ^2.25.0）
    • 计算出满足条件的最新版本组合
    • 创建新的 poetry.lock 文件
    • 然后安装这些版本

2. poetry.lock 是怎么来的？

  • 当你运行 poetry add, poetry remove, 或 poetry update 时
  • Poetry 会重新计算依赖关系
  • 并更新 poetry.lock 文件，记录：
    • 每个包的精确版本
    • 下载 URL
    • 内容的 SHA-256 哈希值
    • 依赖树结构

💡 这就像 pip 的 requirements.txt + pip freeze，但更强大、更安全。

✅ 举个例子

假设 pyproject.toml 中写着：

[tool.poetry.dependencies]
requests = "^2.25.0"

这表示：安装 2.25.0 及以上，但小于 3.0 的版本。

而 poetry.lock 中可能记录：

[[package]]
name = "requests"
version = "2.31.0"

当你 poetry install 时，安装的就是 2.31.0，哪怕现在最新是 2.32.0。

🔄 对比：poetry install vs poetry update

命令读取文件行为
poetry install✅ 优先读 poetry.lock安装 .lock 中锁定的精确版本
poetry update❌ 忽略 poetry.lock重新解析 pyproject.toml，升级到最新兼容版本，并生成新的 .lock

🎯 所以：

  • 开发/部署时用 poetry install（稳定）
  • 想升级依赖时用 poetry update（更新）

📦 实际流程图

poetry install│├── 有 poetry.lock？ → 按 .lock 安装（精确版本）│└── 没有 poetry.lock？ → 根据 pyproject.toml 计算并创建 .lock，然后安装

✅ 最佳实践建议

  1. 提交 poetry.lock 到 Git

    # 不要忽略它！
# .gitignore 中不要包含：
# poetry.lock

    这样团队成员运行 poetry install 时环境才一致。

  2. CI/CD 和生产环境必须使用 poetry install

    # GitHub Actions 示例
- run: poetry install

    确保部署环境和本地测试环境一致。

  3. 不要手动编辑 poetry.lock

    • 它是自动生成的
    • 手动改可能破坏哈希校验

✅ 总结

问题回答
poetry install 只读 .lock 文件吗？✅ 是的，优先且主要依赖 poetry.lock
它会读 pyproject.toml 吗？会，但仅用于验证或生成 .lock（当 .lock 不存在时）
为什么 .lock 很重要？确保依赖版本一致，避免“在我机器上能跑”问题
能跳过 .lock 安装吗？不能。这是设计目标：可重现性

🎯 一句话记住：
pyproject.toml 是“依赖声明”，poetry.lock 是“依赖快照”，
poetry install 安装的是快照，不是声明。

http://www.dtcms.com/a/330266.html

相关文章：

  • 《深入解析C++中的Map容器：键值对存储的终极指南》
  • 基于51单片机zigbee的病房呼叫系统
  • Datawhale AI夏令营 「2025全球AI攻防挑战赛-赛道一：图片全要素交互认证-生成赛」的赛事项目实践
  • springboot接口请求参数校验
  • 双椒派E2000D系统盘制作全攻略
  • 在腾讯云CodeBuddy上实现一个AI聊天助手
  • 实盘回测一体的期货策略开发：tqsdk获取历史数据并回测，附python代码
  • java循环分页查询数据，任何把查询到的数据，分批处理，多线程提交到数据库清洗数据
  • 第十二节：粒子系统：海量点渲染
  • 远程办公，如何轻松访问公司内网？出差在外也能远程控制局域网内电脑、外网直接连接到指定端口应用
  • 基于通用优化软件GAMS的数学建模和优化分析（GAMS安装和介绍、GAMS程序编写、GAMS程序调试）
  • Ubuntu22.04轻松安装Qt与OpenCV库
  • 【力扣】面试经典150题总结02-双指针、滑动窗口
  • Kubernetes 网络排错
  • 《嵌入式Linux应用编程（四）：Linux Framebuffer图形编程》
  • 数学建模算法-day[17]
  • 【Spring Ai框架】
  • CMake笔记：配置(Configure)、生成(Generate)和构建(Build)
  • 软件架构重构：从混沌到有序的系统性演进
  • 第6节 torch.nn介绍
  • 什么是脏读、幻读、不可重复读？
  • linux编程----文件（framebuffer）
  • 正则表达式解析（三）
  • 方法论基础。
  • 与Deepseek对话了解无线电通信知识
  • 自动曝光算法参考
  • Linux Framebuffer（帧缓冲）与基本 UI 绘制技术
  • GitHub宕机时的协作方案
  • 力扣 hot100 Day72
  • Transformer开端