怎么在虚拟环境里用pip25.1的PEP735依赖组?
详细讲解如何在Python虚拟环境中声明和使用pip 25.1引入的PEP 735依赖组功能。涵盖pyproject.toml语法规范、虚拟环境创建与升级、--group参数实操及常见排错指南。
在 Python 3 项目中,要使用 pip 25.1 提供的 PEP 735 依赖组,核心路径分为三步:首先创建并激活项目的独立虚拟环境,随后将该环境内的 pip 升级到 25.1 或更高版本,最后在 pyproject.toml 中通过 [dependency-groups] 声明群组,并直接使用 pip install --group <组名> 命令完成精准安装。
一、理解 PEP 735 依赖组及其与可选依赖的区别
在过去很长一段时间里,Python 项目对“开发类依赖”(如单元测试、代码格式化、类型检查)的管理方式五花八门。有的团队维护多个 requirements-dev.txt 文件,有的使用 Poetry、PDM、Hatch 等专用工具的私有语法,还有不少项目借用了 [project.optional-dependencies](即 Extras 可选依赖)。
这种分歧在 PEP 735(Dependency Groups in pyproject.toml) 获得采纳后迎来了统一标准。PEP 735 在 pyproject.toml 中正式规范了 [dependency-groups] 表,专门用于声明项目的非发布依赖。
依赖组与可选依赖(Extras)的本质差异
初次接触 PEP 735 的开发者常常会问:既然已经有了 [project.optional-dependencies],为什么还要新增一个依赖组?两者的分界线在于软件发布与分发的生命周期:
| 对比维度 | [project.optional-dependencies] (Extras) | [dependency-groups] (PEP 735) |
|---|---|---|
| 主要受众 | 第三方安装者 / 库的使用者 | 项目自身开发者 / CI 测试流水线 |
| 打包与分发 | 写入 Wheel 和 sdist 的 PKG-INFO 元数据中 | 完全不进入分发包元数据,纯本地与开发期保留 |
| 安装命令 | pip install package[extra_name] |
pip install --group group_name |
| 嵌套复用 | 原生不支持嵌套语法 | 支持 include-group 语法相互组合 |
二、操作步骤:创建虚拟环境并升级 pip 至 25.1
PEP 735 的原生 CLI 支持始于 pip 25.1。如果当前环境中的 pip 版本低于 25.1,执行带 --group 的安装命令时,系统将直接抛出 no such option: --group 错误。因此,必须在全新或已有的虚拟环境中确保 pip 处于最新状态。
步骤 1:在项目根目录下创建虚拟环境
打开终端,导航到包含项目代码的根目录,使用 Python 内置的 venv 模块创建一个名为 .venv 的虚拟环境:
python3 -m venv .venv
步骤 2:激活隔离的虚拟环境
激活环境后,终端命令行的前缀会显式出现 (.venv) 提示符,所有后续的包安装操作都将严格限定在该目录中,不会对系统全局 Python 造成任何影响:
source .venv/bin/activate
# PowerShell 执行:
.venv\Scripts\Activate.ps1
# CMD 批处理执行:
.venv\Scriptsctivate.bat
步骤 3:升级 pip 至 25.1 或以上版本
由于 Python 标准库内置的 virtualenv 种子 pip 往往滞后于最新版本,激活后必须显式升级当前环境的 pip:
python -m pip install --upgrade "pip>=25.1"
升级完成后,执行版本查询命令确认输出:
pip --version
三、语法规则:在 pyproject.toml 中声明依赖组
准备好环境之后,需要在项目根目录的 pyproject.toml 文件中添加 [dependency-groups] 配置项。
基本声明与包版本约束
依赖组的定义格式为一个 TOML 表,每个键代表依赖组名称,对应的值为一个由 PEP 508 依赖描述符构成的字符串列表:
[project]
name = "demo-service"
version = "0.1.0"
dependencies = [
"requests>=2.31.0",
]
[dependency-groups]
# 单元测试依赖组
test = [
"pytest>=8.0.0",
"pytest-cov>=5.0.0",
]
# 代码静态分析与规范组
lint = [
"ruff>=0.8.0",
"mypy>=1.13.0",
]
# 文档生成组
docs = [
"sphinx>=7.0.0",
"furo>=2024.0.0",
]
使用 include-group 组合嵌套依赖组
开发工作中经常需要一个包含所有开发工具的“大礼包”组(如 dev)。在以往的做法中,开发者不得不手动将所有包重新罗列一遍,容易产生版本不同步的问题。PEP 735 专门提供了 { include-group = "组名" } 内联语法:
[dependency-groups]
test = ["pytest>=8.0", "coverage>=7.5"]
lint = ["ruff>=0.8.0", "mypy>=1.13"]
# 组合嵌套组:聚合 test 和 lint 组,并追加独立工具
dev = [
{ include-group = "test" },
{ include-group = "lint" },
"pre-commit>=4.0.0",
]
当 pip 25.1 处理 dev 组时,它会在内存中自动展开包含的依赖子项,并将依赖列表展平、去重,最终一次性交由依赖求解器完成版本决议。
四、终端实战:使用 pip --group 安装依赖组
当虚拟环境已激活且当前工作目录位于 pyproject.toml 所在路径时,即可调用 pip 25.1 的新增参数执行安装。
1. 安装单个依赖组
直接通过 --group 选项指定目标组名:
pip install --group test
2. 同时安装多个依赖组
如果需要同时装入测试与代码检查工具,重复传入 --group 参数即可:
pip install --group test --group lint
3. 结合项目自身的可编辑安装(-e .)
在进行库文件或应用系统的日常开发时,通常需要将项目源码以“可编辑模式”(Editable Mode)挂载到虚拟环境中,并同时装配开发依赖组:
pip install -e . --group dev
这条命令首先会把当前项目以可编辑模式链接到虚拟环境的 site-packages,同时解析 pyproject.toml 中的 dev 依赖组并安装所有必需工具。
五、关键规则与常见排错指南
在虚拟环境中使用 PEP 735 依赖组时,通常有以下几个高频出现的问题值得关注:
根本原因:当前命令调用的是系统的旧版本 pip,或者虚拟环境创建后未执行 pip 升级。
排查与修复:在当前终端执行 which pip(Windows 下使用 where.exe pip)核实路径是否在当前 .venv 目录中。确认路径正确后,运行 python -m pip install --upgrade "pip>=25.1" 即可。
根本原因:pip 默认会在当前 Shell 的执行路径(Current Working Directory)寻找配置文件。
排查与修复:确认当前工作路径正是包含 pyproject.toml 的根目录,不要进入子包目录下盲目执行命令。
根本原因:在定义复合组时出现了相互嵌套(例如组 A 包含组 B,而组 B 又通过 include-group 引用了组 A)。
排查与修复:PEP 735 明确禁止循环引用,pip 在递归展开时会直接终止并报错。应将通用基础工具拆解为原子化的独立组,统一由单向复合组(如 dev)自上而下进行聚合。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









