extras_require与dependencygroups区别详解

本文深入解析了 Python 项目中 `extras_require` 与新兴的 `dependency-groups` 的核心区别与实践陷阱：在现代 `pyproject.toml`（PEP 621）体系下，`extras_require` 已被弃用，必须改用 `[project.optional-dependencies]`，否则 pip 会静默忽略导致可选依赖完全不生效；而 `dependency-groups`（PEP 732）尚属实验性功能，缺乏生态支持且不兼容旧版工具，当前生产环境务必避免使用；文章还揭示了依赖冲突的隐蔽性——版本锁定易引发间接降级，强调通过 `--dry-run`、`pip check` 和 `pipdeptree` 主动检测，帮助开发者避开“安装成功却运行报错”的典型坑。

pip install 时 extras_require 不生效？检查 pyproject.toml 里有没有写错格式

Python 3.11+ 默认用 pyproject.toml，但很多人照搬旧的 setup.py 写法，把 extras_require 直接塞进 [project] 段——这不行。pip 会静默忽略它，装包时不报错，但 pip install mypkg[dev] 就是不装 dev 依赖。

正确位置是 [project.optional-dependencies]（注意不是 extras_require），这是 PEP 621 规定的字段名。旧项目迁移到 pyproject.toml 时最容易漏改这个。

• extras_require 只在 setup.py 或 setup.cfg 中有效；pyproject.toml 里必须用 optional-dependencies
• 键名支持点号（如 "lint:typing"），但值必须是字符串列表，不能是字典或带条件表达式（如 "typing; python_version < '3.12'" 需写成字符串）
• 如果同时存在 setup.py 和 pyproject.toml，pip 优先读 pyproject.toml，旧 setup.py 的 extras_require 完全不生效

dependency groups 是什么？和 optional-dependencies 不是一回事

dependency-groups 是 PEP 732 提出的新机制，目前（截至 pip 24.0）只在实验性支持阶段，需显式启用：pip install --config-settings editable-verbose=true mypkg 并配合 [dependency-groups] 段。它和 optional-dependencies 本质不同：后者是“可选依赖”，前者是“开发/构建/测试等场景专用依赖组”，语义更细、支持跨环境隔离。

现在绝大多数项目、CI 流程、IDE 插件（如 VS Code 的 Python 扩展）都只认 optional-dependencies。盲目写 [dependency-groups] 会导致 pip install mypkg[test] 报错：no such extra。

• 当前生产环境请坚持用 [project.optional-dependencies]，别碰 [dependency-groups]
• dependency-groups 不兼容旧版 pip（<23.3），且不被 Poetry、uv 等工具识别
• 它允许声明依赖之间的执行顺序（如 test → lint → typecheck），但现阶段纯属理论优势，没实际落地支撑

条件依赖写在哪？extras_require / optional-dependencies 里不能直接写平台判断

想实现“Windows 下装 pywin32，Linux 下跳过”，不能在 optional-dependencies 值里直接写 ["pywin32; sys_platform == 'win32'"]——这语法合法，但 pip 在解析时不会动态求值，而是当成普通字符串处理，最终可能误装或漏装。

真正起作用的是 PEP 508 环境标记（environment markers），必须作为字符串的一部分，且只能出现在依赖项末尾，用分号隔开。格式严格："pywin32; sys_platform == 'win32'"，不能多空格、不能换行、不能嵌套括号。

• 环境标记只支持标准字段（python_version, sys_platform, platform_system 等），不支持自定义变量
• 多个条件用 and/or 连接，例如："requests; python_version >= '3.8' and platform_system != 'Windows'"
• 如果条件逻辑复杂（比如要排除多个平台），建议拆成多个 extra，靠用户手动选，比写一堆标记更可靠

install_requires 和 optional-dependencies 的依赖冲突怎么查？

当 install_requires 里写了 requests>=2.25，而 optional-dependencies.test 里又写了 requests==2.20.0，pip 不会自动报错，而是按安装顺序覆盖——很可能导致运行时报 AttributeError。

这种冲突没法靠看文件发现，得靠 pip install --dry-run 或 pipdeptree --warn duplicate 来暴露。尤其要注意间接依赖：你的 test extra 依赖的某个包，可能自带一个老版本 requests，悄悄降级了主依赖。

• 本地验证命令：pip install .[test] --dry-run 2>&1 | grep requests
• CI 中建议加一步：pip check，它能发现已安装包之间的版本冲突
• 避免在 extra 中锁定主依赖的版本（如 requests==2.20.0），优先用兼容范围：requests>=2.20.0,<3

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《extras_require与dependencygroups区别详解》文章吧，也可关注golang学习网公众号了解相关技术文章。