【Python】pdm 与 poetry 用法整理

概要

PDM (Python Dependency Manager) 和 Poetry 是当前最主流的两个 Python 包管理 / 依赖管理工具，均采用 pyproject.toml 规范。PDM 对标 npm 风格，Poetry 更接近传统 pip+virtualenv 体验。

---

PDM 官网： https://pdm-project.org
GitHub： https://github.com/pdm-project/pdm

PDM

基础

安装 PDM

bash

pip install pdm
# or
pipx install pdm

初始化项目

bash

pdm init

交互式问答创建 pyproject.toml，选择 Python 版本并决定是否创建虚拟环境。

完成后会生成：

• pyproject.toml — 项目元数据和依赖声明
• pdm.lock — 锁定文件，需提交到版本控制
• .pdm-python — 项目 Python 路径（不要提交）
• .venv/ — 虚拟环境目录

查看信息

bash

pdm -h                  # 帮助
pdm info                # 项目信息（版本、Python 路径、项目根目录）

切换 Python 版本

bash

pdm use python3.9       # 切换到指定版本
pdm use                 # 从列表中选择
pdm python install 3.12 # 先安装缺失的版本，再 use

requires-python 约束版本范围（如 >=3.9），切换的版本必须在此范围内。

---

依赖管理

添加依赖

bash

pdm add requests
pdm add "requests==2.25.1"
pdm add "requests[socks]"
pdm add "flask>=1.0" flask-sqlalchemy
 
# 开发依赖
pdm add -d pytest
pdm add -dG test pytest pytest-cov
pdm add -dG lint flake8 black
 
# 其他来源
pdm add ./sub-package
pdm add "git+https://github.com/pypa/pip.git@22.0"
 
# 可编辑模式（仅开发依赖）
pdm add -e ./sub-package --dev

保存版本策略

bash

pdm add requests --save-minimum     # >=2.21.0 (默认)
pdm add requests --save-compatible  # >=2.21.0,<3.0.0
pdm add requests --save-exact       # ==2.21.0
pdm add requests --save-wildcard    # * (不限制)

更新 / 移除 / 查看

bash

pdm update                  # 更新全部
pdm update requests         # 更新指定包
pdm update -u requests      # 忽略版本约束
 
pdm remove requests
pdm remove -d pytest
 
pdm list                    # 列出当前环境包
pdm list --graph            # 树形依赖图
pdm list --outdated         # 检查过期包

---

虚拟环境

bash

pdm venv create 3.9                     # 创建
pdm venv create --name for-test 3.9     # 指定名称
pdm venv list                           # 列出
pdm venv remove for-test                # 删除
 
# 激活（打印命令，不进入子 shell）
eval $(pdm venv activate for-test)      # Bash/Zsh
eval (pdm venv activate for-test)       # Fish
Invoke-Expression (pdm venv activate for-test)  # PowerShell
 
# 或直接用 pdm run
pdm run python script.py
pdm run flask run -p 54321

---

PDM Scripts（类 Makefile 任务）

在 pyproject.toml 的 [tool.pdm.scripts] 中定义：

toml

[tool.pdm.scripts]
start = "flask run -p 54321"
test = "pytest"
lint = "flake8"
filter_error = {shell = "cat error.log | grep CRITICAL > critical.log"}
all = {composite = ["lint", "test"]}

执行：

bash

pdm run start
pdm run start -h 0.0.0.0   # 附加参数
pdm run all                 # 依次执行 lint + test

---

其他常用命令

命令	用途
pdm install	安装所有依赖
pdm sync	同步环境与锁文件（清理多余包）
pdm build	构建分发包 (sdist + wheel)
pdm publish	上传到 PyPI
pdm export	导出 requirements.txt
pdm import	从 Pipfile/requirements.txt 导入
pdm config	配置 PDM 行为
pdm python install	安装独立 Python 解释器
pdm python list	列出已安装的解释器

---

Poetry 官网： https://python-poetry.org
GitHub： https://github.com/python-poetry/poetry

Poetry

基础

安装 Poetry

bash

# 推荐方式（独立安装，不受项目 venv 影响）
curl -sSL https://install.python-poetry.org | python3 -
 
# 或通过 pipx
pipx install poetry
 
# 或通过 pip（不推荐）
pip install poetry

新建项目

bash

poetry new poetry-demo

生成目录结构：poetry-demo/pyproject.toml, src/poetry_demo/, tests/

初始化已有项目

bash

cd pre-existing-project
poetry init

查看信息

bash

poetry about       # 版本信息
poetry --version   # 简略版本

切换 Python 版本

bash

poetry env use /full/path/to/python
poetry env use python3.7
poetry env use 3.7
poetry env use system    # 恢复默认

Poetry 默认使用安装 Poetry 时的 Python 版本，可通过 env use 切换。配合 pyenv 更方便。

---

依赖管理

添加依赖

bash

poetry add pendulum
poetry add "pendulum>=2.0.5"
poetry add pendulum==2.0.5
poetry add pendulum@^2.0.5          # 兼容最新 minor
poetry add pendulum@~2.0.5          # 兼容最新 patch
poetry add pendulum@latest          # 最新版本
 
# extras
poetry add "requests[security,socks]"
 
# 开发依赖
poetry add pytest --group dev
poetry add pytest --dev             # 快捷方式（等同于 -G dev）
 
# Git / 本地
poetry add git+https://github.com/sdispater/pendulum.git
poetry add git+https://github.com/sdispater/pendulum.git#develop
poetry add ./my-package/
poetry add ../my-package/dist/my-package-0.1.0.tar.gz
 
# 可编辑模式
poetry add --editable ./my-package/

更新 / 移除 / 查看

bash

poetry update                  # 更新全部
poetry update pendulum         # 更新指定包
 
poetry remove pendulum
poetry remove pytest --group dev
 
poetry show                    # 列出已安装包
poetry show --tree             # 树形依赖
poetry show --outdated         # 检查过期
poetry show pendulum           # 查看指定包详情

---

虚拟环境

Poetry 默认在 {cache-dir}/virtualenvs/ 下管理 venv。可配置 virtualenvs.in-project=true 改为项目内 .venv/。

bash

poetry env use 3.9             # 切换环境
poetry env info                # 查看当前环境信息
poetry env info --path         # 仅显示路径
poetry env info --executable   # 仅显示 Python 路径
poetry env list                # 列出所有环境
poetry env list --full-path    # 显示完整路径
poetry env remove 3.7          # 删除指定版本环境
poetry env remove --all        # 全部删除
 
# 激活环境
eval $(poetry env activate)

运行命令

bash

poetry run python your_script.py
poetry run pytest
poetry run black .

---

常用命令

命令	用途
poetry install	安装所有依赖（无 lock 时自动生成 lock）
poetry install --no-root	仅安装依赖，不安装项目本身（非 package 模式）
poetry lock	仅更新 lock 文件，不安装
poetry build	构建分发包 (sdist + wheel)
poetry publish	上传到 PyPI
poetry export	导出 requirements.txt
poetry config	配置项管理
poetry cache list	列出缓存
poetry cache clear --all	清空缓存
poetry version	显示/更新版本号
poetry check	验证 pyproject.toml 格式

关于 package mode

默认 Poetry 以 package 模式运行（会构建和发布包）。如果只用 Poetry 管理依赖而不发布包，可设置：

toml

[tool.poetry]
package-mode = false

---

附录

原生 venv 用法（无工具）

cmd

python -m venv ENV_DIR
.\ENV_DIR\Scripts\activate       # Windows
source ENV_DIR/bin/activate       # Unix/macOS
deactivate

快速对比

特性	PDM	Poetry
安装方式	pip install pdm	`curl …
lock 文件	pdm.lock	poetry.lock
虚拟环境位置	项目内 .venv/	{cache-dir}/virtualenvs/
脚本任务	[tool.pdm.scripts]	—（需插件或 makefile）
依赖分组	-d / -dG	--group / --dev
包发布	pdm publish	poetry publish
PEP 582 支持	原生	不支持
单文件脚本 (PEP 723)	支持 (pdm run script.py)	不支持
可编辑模式	仅 dev 依赖	支持
命令风格	接近 npm/yarn	传统 CLI