Python包管理之Protry的基本使用

一，Poetry是什么

Poetry是Python生态中一款革命性的​​依赖管理与项目打包工具​​，它通过现代化的设计理念解决了传统工具（如pip+virtualenv）在项目管理中的诸多痛点，比 pip 的功能强大许多。

核心功能如下：

1，智能依赖管理​

Poetry采用 pyproject.toml 文件统一管理项目元数据、依赖声明及构建配置，通过poetry add <package>命令即可自动解析依赖树并安装精确版本，避免版本冲突（如同时安装Django 4.2和5.0导致的兼容性问题）。

2，​​虚拟环境自动化

每个项目默认创建独立虚拟环境（路径统一存储在系统目录），通过 poetry shell 快速激活环境，且支持自定义虚拟环境存放位置（如项目目录下），确保开发环境隔离性。这对需要同时维护多个Python版本的项目尤为重要。

3，版本锁定机制​

生成的poetry.lock文件会​​精确记录所有依赖的哈希值与版本号​​，确保开发、测试、生产环境的一致性，彻底消除"在我机器上能运行"的协作难题。团队协作时只需共享此文件即可复现完全相同的依赖环境。

4，全流程项目管理

从初始化（poetry new）、依赖安装到打包发布（poetry build/poetry publish）提供完整工具链，支持PyPI私有仓库配置，满足企业级项目发布需求。例如发布时自动处理setup.py生成和版本号校验。

---

二，pip的不足

pip 是 python 内置的依赖管理工具，而它最大的不足在于第三方模块的相关性依赖管理的能力不足。尤其是在删除第三方模块是的依赖解析， 可以说是不会分析依赖。如使用pip删除下载的依赖时，不会删除下载依赖时顺带下载的依赖，导致虚拟环境留下一堆依赖。

下载依赖如下：

(venv) D:\code_demo>pip install flask
(venv) D:\code_demo>pip list
Package      Version
------------ -------
blinker      1.6.2
click        8.1.3
colorama     0.4.6
Flask        2.3.2
itsdangerous 2.1.2
Jinja2       3.1.2
MarkupSafe   2.1.2
pip          22.3.1
setuptools   65.5.0
Werkzeug     2.3.6

删除依赖如下：会发现只删除了 flask 模块

(venv) D:\code_demo>pip uninstall flask
(venv) D:\code_demo>pip list
Package      Version
------------ -------
blinker      1.6.2
click        8.1.3
colorama     0.4.6
itsdangerous 2.1.2
Jinja2       3.1.2
MarkupSafe   2.1.2
pip          22.3.1
setuptools   65.5.0
Werkzeug     2.3.6

---

三，从零开始使用 Poetry

1，安装

安装之后就会在 python 解释器的安装目录下的 Scripts 目录里面出现 poetry.exe，因为在安装 python 解释器时配置过环境变量，然后就可以直接全局使用了。

pip install poetry

2，使用 Poetry - pip切换poetry

删除项目中已存在的 .venv 目录，使用如下命令初始化

poetry init

初始化后会弹出一连串对话，一直回车，可以看到在项目下生成了一个 pyproject.toml 文件

[project]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = [
    {name = "Hva",email = "33451625290@qq.com"}
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [ # 依赖管理
]


[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

创建虚拟环境

重点说明

• 虚拟环境的命名模式为：项目名-随机数-python版本
• 虚拟环境创建在： C:\Users\<用户名>\AppData\Local\pypoetry\Cache\virtualenvs
• poetry env use python 是使用当前命令行下激活的 python 解释器创建虚拟环境，也可以将python修改为python3之类的

(.venv) PS D:\DsxsSpace\demo> poetry env use python
Creating virtualenv demo-2hej9_fo-py3.9 in C:\Users\17585\AppData\Local\pypoetry\Cache\virtualenvs
Using virtualenv: C:\Users\17585\AppData\Local\pypoetry\Cache\virtualenvs\demo-2hej9_fo-py3.9

修改虚拟环境存放位置

修改 poetry 的全局配置，删除已经创建的虚拟环境，重新让虚拟环境创建在项目根目录之下

(.venv) PS D:\DsxsSpace\demo> poetry config virtualenvs.in-project true
(.venv) PS D:\DsxsSpace\demo> poetry env remove python
Deleted virtualenv: C:\Users\17585\AppData\Local\pypoetry\Cache\virtualenvs\demo-2hej9_fo-py3.9
(.venv) PS D:\DsxsSpace\demo> poetry env use python
Creating virtualenv demoin D:\DsxsSpace\demo\.venv
Using virtualenv: D:\DsxsSpace\demo\.venv

3，poetry指令

安装依赖

poetry add 依赖名称

相较于 pip install ，poetry 会将所有的信息全部列出来，并且清楚的告知了新增了那些第三方模块。

(poetry-demo-py3.9) PS D:\django-item\Poetry-demo> poetry add flask
Using version ^3.1.0 for flask

Updating dependencies
Resolving dependencies... (6.3s)

Package operations: 10 installs, 0 updates, 0 removals

  - Installing colorama (0.4.6)
  - Installing markupsafe (3.0.2)
  - Installing zipp (3.21.0)
  - Installing blinker (1.9.0)
  - Installing click (8.1.8)
  - Installing importlib-metadata (8.6.1)
  - Installing itsdangerous (2.2.0)
  - Installing jinja2 (3.1.6)
  - Installing werkzeug (3.1.3)
  - Installing flask (3.1.0)

Writing lock file
(poetry-demo-py3.9) PS D:\django-item\Poetry-demo>

项目中的 pyproject.toml 只会增加 flask 这个模块到依赖中，不会将其他顺带的第三方模块也添加进来

dependencies = [
    "flask (>=3.1.0,<4.0.0)"  # 新增部分
]

poetry.lock与更新

除了更新 pyproject.toml ，此时项目中还会新增一个文件，名为 poetry.lock ，它实际上就相当于 pip 的 requirements.txt ，详细记录了所有安装的模块与版本。

当使用 poetry add 指令时，poetry 会自动依序帮你做完这三件事：

1. 更新 pyproject.toml。
2. 依照 pyproject.toml 的内容，更新 poetry.lock 。
3. 依照 poetry.lock 的内容，更新虚拟环境。

当你自行修改了 pyproject.toml 内容，比如变更特定模块的版本（这是有可能的，尤其在手动处理版本冲突的时候），此时 poetry.lock 的内容与 pyproject.toml 出现了脱钩，必须让它依照新的 pyproject.toml 内容更新、同步。

但要特别注意的是， poetry lock 指令，仅会更新 poetry.lock ，不会同时安装模块至虚拟环境。因此，在执行完 poetry lock 指令后，必须再使用 poetry install 来安装模块。否则就会出现 poetry.lock 和虚拟环境不一致的状况。

使用指令：

poetry lock
poetry install

新增模块至 dev-dependencies

有些模块，比如 pytest 、 black 等等，只会在开发环境中使用，产品的部署环境并不需要。

Poetry 允许你区分这两者，将上述的模块安装至 dev-dependencies 区块，方便让你轻松建立一份「不包含」 dev-dependencies 开发模块的安装清单

poetry add black --group dev

Poetry更新模块

poetry update

// 更新指定模块
poetry update requests toml

列出全部模块清单

这里的清单内容并不是来自于虚拟环境，这点和 pip 不同，而是来自于 poetry.lock 的内容。

树状显示模块依赖层级

poetry show --tree

显示指定模块的依赖层级

poetry show flask --tree

Poetry 移除模块

poetry remove flask

输出 Poetry 虚拟环境的 requirements.txt

poetry export -f requirements.txt -o requirements.txt --without-hashes

// 指定 dev 环境
poetry export -f requirements.txt -o requirements.txt --without-hashes --dev

修改 poetry 镜像源

// 修改为清华镜像源
poetry source add tsinghua https://pypi.tuna.tsinghua.edu.cn/simple