怎么在虚拟环境里用pip25.1的PEP735依赖组?

听雨眠
听雨眠
发布时间:2026-11-21 | 5人浏览过
原创

详细讲解如何在Python虚拟环境中声明和使用pip 25.1引入的PEP 735依赖组功能。涵盖pyproject.toml语法规范、虚拟环境创建与升级、--group参数实操及常见排错指南。

Python 依赖管理实战

在 Python 3 项目中,要使用 pip 25.1 提供的 PEP 735 依赖组,核心路径分为三步:首先创建并激活项目的独立虚拟环境,随后将该环境内的 pip 升级到 25.1 或更高版本,最后在 pyproject.toml 中通过 [dependency-groups] 声明群组,并直接使用 pip install --group <组名> 命令完成精准安装。

怎么在虚拟环境里用pip25.1的PEP735依赖组?
图 0:PEP 735 依赖组与 pip 25.1 虚拟环境协同工作概览

一、理解 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 语法相互组合
怎么在虚拟环境里用pip25.1的PEP735依赖组?
图 1:[project.optional-dependencies] 与 [dependency-groups] 的元数据发布边界对比

二、操作步骤:创建虚拟环境并升级 pip 至 25.1

PEP 735 的原生 CLI 支持始于 pip 25.1。如果当前环境中的 pip 版本低于 25.1,执行带 --group 的安装命令时,系统将直接抛出 no such option: --group 错误。因此,必须在全新或已有的虚拟环境中确保 pip 处于最新状态。

步骤 1:在项目根目录下创建虚拟环境

打开终端,导航到包含项目代码的根目录,使用 Python 内置的 venv 模块创建一个名为 .venv 的虚拟环境:

终端命令(Linux / macOS / Windows Bash) bash
python3 -m venv .venv

步骤 2:激活隔离的虚拟环境

激活环境后,终端命令行的前缀会显式出现 (.venv) 提示符,所有后续的包安装操作都将严格限定在该目录中,不会对系统全局 Python 造成任何影响:

Linux / macOS 激活命令 bash
source .venv/bin/activate
Windows PowerShell / CMD 激活命令 powershell
# PowerShell 执行:
.venv\Scripts\Activate.ps1

# CMD 批处理执行:
.venv\Scriptsctivate.bat

步骤 3:升级 pip 至 25.1 或以上版本

由于 Python 标准库内置的 virtualenv 种子 pip 往往滞后于最新版本,激活后必须显式升级当前环境的 pip:

升级 pip 命令 bash
python -m pip install --upgrade "pip>=25.1"

升级完成后,执行版本查询命令确认输出:

版本校验命令 bash
pip --version
示例终端输出 pip 25.1 from /path/to/project/.venv/lib/python3.11/site-packages/pip (python 3.11)
怎么在虚拟环境里用pip25.1的PEP735依赖组?
图 2:在虚拟环境中就绪 pip 25.1 的标准化操作流程

三、语法规则:在 pyproject.toml 中声明依赖组

准备好环境之后,需要在项目根目录的 pyproject.toml 文件中添加 [dependency-groups] 配置项。

基本声明与包版本约束

依赖组的定义格式为一个 TOML 表,每个键代表依赖组名称,对应的值为一个由 PEP 508 依赖描述符构成的字符串列表:

pyproject.toml 示例配置 toml
[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 = "组名" } 内联语法:

pyproject.toml 中嵌套复用依赖组 toml
[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 组时,它会在内存中自动展开包含的依赖子项,并将依赖列表展平、去重,最终一次性交由依赖求解器完成版本决议。

怎么在虚拟环境里用pip25.1的PEP735依赖组?
图 3:PEP 735 中 include-group 的展开与聚合解析机制

四、终端实战:使用 pip --group 安装依赖组

当虚拟环境已激活且当前工作目录位于 pyproject.toml 所在路径时,即可调用 pip 25.1 的新增参数执行安装。

1. 安装单个依赖组

直接通过 --group 选项指定目标组名:

安装测试依赖组 bash
pip install --group test
示例终端输出 Processing pyproject.toml (dependency group: test) Collecting pytest>=8.0.0 Downloading pytest-8.3.4-py3-none-any.whl (343 kB) Collecting coverage>=7.5.0 Downloading coverage-7.6.9-cp311-cp311-manylinux.whl (234 kB) Installing collected packages: coverage, iniconfig, pluggy, pytest Successfully installed coverage-7.6.9 iniconfig-2.0.0 pluggy-1.5.0 pytest-8.3.4

2. 同时安装多个依赖组

如果需要同时装入测试与代码检查工具,重复传入 --group 参数即可:

多组联合安装 bash
pip install --group test --group lint

3. 结合项目自身的可编辑安装(-e .)

在进行库文件或应用系统的日常开发时,通常需要将项目源码以“可编辑模式”(Editable Mode)挂载到虚拟环境中,并同时装配开发依赖组:

项目本体与依赖组协同安装 bash
pip install -e . --group dev

这条命令首先会把当前项目以可编辑模式链接到虚拟环境的 site-packages,同时解析 pyproject.toml 中的 dev 依赖组并安装所有必需工具。

五、关键规则与常见排错指南

在虚拟环境中使用 PEP 735 依赖组时,通常有以下几个高频出现的问题值得关注:

排错 1:报错 no such option: --group

根本原因:当前命令调用的是系统的旧版本 pip,或者虚拟环境创建后未执行 pip 升级。

排查与修复:在当前终端执行 which pip(Windows 下使用 where.exe pip)核实路径是否在当前 .venv 目录中。确认路径正确后,运行 python -m pip install --upgrade "pip>=25.1" 即可。

排错 2:报错 File "pyproject.toml" not found

根本原因:pip 默认会在当前 Shell 的执行路径(Current Working Directory)寻找配置文件。

排查与修复:确认当前工作路径正是包含 pyproject.toml 的根目录,不要进入子包目录下盲目执行命令。

排错 3:循环包含(Circular Dependency Loop)

根本原因:在定义复合组时出现了相互嵌套(例如组 A 包含组 B,而组 B 又通过 include-group 引用了组 A)。

排查与修复:PEP 735 明确禁止循环引用,pip 在递归展开时会直接终止并报错。应将通用基础工具拆解为原子化的独立组,统一由单向复合组(如 dev)自上而下进行聚合。

怎么在虚拟环境里用pip25.1的PEP735依赖组?
图 4:pip 25.1 依赖组全流程检查与排错决策卡
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表