# 优点

思考这样一种情况 ——

	pip install A
	pip uninstall A

安装包 A 时，你会安装一大堆依赖；uninstall 后，A 删了，但是安装的一堆依赖还在

于是 poetry 横空出世，这种问题迎刃而解。poetry 的优点如下：

通过 pyproject.toml 声明依赖，并自动用 poetry.lock 锁定所有包（包括子依赖）的具体版本，这样能保证不同环境中安装一致、避免 “在我机器上能跑” 的问题
集成虚拟环境管理，一口气安装、打包、发布等操作

Poetry 本身依赖很多包（>30 个），所以在安装 Poetry 时，把它放在一个专门的虚拟环境中

官方也明确指出：Poetry 应该始终安装在专用虚拟环境中，绝不可安装到要被它管理的项目环境里

偷懒了，我安装在全局环境了（以后可能会有问题），后面再改：

pip install poetry

# 指令总结

# 初始化

在对应文件夹下运行：

poetry init

生成 pyproject.toml 文件

# 虚拟环境

Poetry 预设上（可通过 poetry config 修改）会强制要求依赖包都要安装在虚拟环境中，所以它整合了 virtualenv 。

在执行 poetry add、install 等指令时，Poetry 都会自动检查：

如果是虚拟环境，直接在当前虚拟环境操作。
如果否，则会自动帮你创建一个新的虚拟环境，然后再安装模块

预设所有虚拟环境创建在创建在 C:\Users\<用户名>\AppData\Local\pypoetry\Cache\virtualenvs 下，可修改设置为当前工程目录内

手动创建虚拟环境：

poetry env use python

启动与退出虚拟环境须在项目根目录下：

	poetry shell # 进入
	exit # 退出

# 添加包

添加包到工程：

poetry add numpy

pyproject.toml 的 dependencies 条目新增 numpy 条目；
同时 poetry.lock 文件增加所有依赖包，lock 文件相当于 pip 的 requirements.txt

poetry add 指令会做三件事：

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

poetry.lock 的内容是取决于 pyproject.toml ，但两者并不会自己连动，要基于特定指令

poetry 与 pip 不同，requirements.txt 对依赖包的版本是写死的；poetry 能力强，所以能放心通过范围指定依赖包版本：

	poetry add django@^4.2.9 # 接受所有 [4.2.9, 5.0.0) 的更新
	poetry add django@~4.2.9 # 接受所有 [4.2.9, 4.3.0) 的更新
	poetry add "django>=4.2.9" # 无上限，注意这里使用「字符串」表示
	poetry add django==4.2.9 # 锁死，但也浪飞了 poetry 的管理能力

无上限容易引入 breaking change，即重大变更 $(4.x.x -> 5.x.x)$ ，不建议

# 更新挂钩

如若手动修改 pyproject.toml 的内容，比如变更某模块的版本，lock 和 toml 脱钩了

lock 要依照 toml 更新：

poetry lock

虚拟环境要根据 lock 更新：

poetry install

# 区分开发环境

不赘述，我不常用，仅列出参考：

	poetry add black --dev
	# 或
	poetry add black -D

# 更新包

注，更新操作会被 add 时指定的版本范围约束，如要为了打破约束，请重新 add

	poetry update # 全部
	poetry update requests toml # 只更新这俩包

# 列出全部

类似 pip list

poetry show

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

树状显示依赖 **（最有用的一集）** ：

	poetry show --tree # 全部
	poetry show numpy --tree # 指定包

# 移除包

使用 poetry remove 指令。和 poetry add 一样，可以加上 -D 参数来移除置于开发区的模块。

poetry remove flask

# 输出 requirements.txt

2025/05/24 ：在 Poetry 2.0 以後， export 指令需要額外安裝才行，具體可參考官方文件。

若要 docker+poetry，启动容器后需要先安装 Poetry 到全域，或打包一个带有 Poetry 的 image，两者都会增加新的耦合与依赖 ，需要更细致的管理（但 multi-stage build 可以解决这个问题）

所以不推荐在 docker 中使用 poetry，我们此时需要 requirements.txt（根据 poetry.lock 的内容，输出一份 requirements.txt 档案）：

poetry export -f requirements.txt -o requirements.txt --without-hashes  # 去除预设的 hash 值

poetry