Dependency Groups (PEP 735 Implementation)

1.3.1 · active · verified Thu Apr 09

The `dependency-groups` library is an active implementation of PEP 735, a standard defining a mechanism for storing package requirements in `pyproject.toml` files that are not included in built project metadata. This library, currently at version 1.3.1 and maintained by the Python Packaging Authority, enables parsing and resolving these dependency groups, including handling nested group inclusions. It's primarily used for development-time dependencies like testing, linting, or documentation, distinguishing them from runtime or optional user-facing dependencies.

Warnings

gotcha PEP 735 (Dependency Groups) is a relatively new standard (accepted October 2024). While `dependency-groups` implements the specification, broader tooling support (e.g., `pip`, `uv`, `poetry`) is still evolving. Ensure your entire toolchain supports dependency groups as expected.
Fix: Consult the documentation of your package manager (e.g., `pip`, `uv`, `poetry`, `pdm`) for their current level of PEP 735 support. Keep tools updated to their latest versions.
gotcha Avoid creating dependency group names that match existing `project.optional-dependencies` names. PEP 735 advises against this, and tools may treat such name collisions as errors or lead to confusing behavior due to overlapping install UX.
Fix: Use distinct names for your dependency groups (in `[dependency-groups]`) and optional dependencies (in `[project.optional-dependencies]`) within your `pyproject.toml`.
gotcha Dependency group includes must not contain cycles (e.g., group A includes B, and B includes A). Tools implementing PEP 735, including `dependency-groups`, are expected to detect and report errors if cycles are found during resolution.
Fix: Carefully structure your `include-group` declarations in `pyproject.toml` to ensure no circular dependencies exist between your groups.
gotcha Dependency groups are explicitly *not* included in the project's metadata when a package is built and distributed (e.g., to PyPI). They are intended for local development workflows and not for end-user installation via standard package managers.
Fix: For runtime optional features that users can install, use `project.optional-dependencies`. For core runtime dependencies, use `project.dependencies`.

Install

pip install dependency-groups Core library
pip install "dependency-groups[cli]" With CLI tools (includes tomli for older Pythons)

Imports

resolve
```
from dependency_groups import resolve
```
A functional interface to resolve a dependency group to a list of strings.
DependencyGroupResolver
```
from dependency_groups import DependencyGroupResolver
```
An object-oriented interface for more advanced resolution and inspection.

Quickstart

This quickstart demonstrates how to parse `dependency-groups` from a `pyproject.toml` (simulated here as a string) and use the `resolve` function to get a flattened list of requirements for a specific group, including handling nested `include-group` directives.

import tomllib
import io
from dependency_groups import resolve

# Simulate a pyproject.toml file content
pyproject_content = """
[dependency-groups]
test = ["pytest", {"include-group": "runtime"}]
runtime = ["flask"]
build = ["build", "twine"]
"""

# In a real project, you would load from 'pyproject.toml':
# with open("pyproject.toml", "rb") as fp:
#     pyproject = tomllib.load(fp)
# groups = pyproject["dependency-groups"]

# For quickstart, load from the string
pyproject = tomllib.load(io.BytesIO(pyproject_content.encode('utf-8')))
groups = pyproject["dependency-groups"]

# Resolve the 'test' dependency group
resolved_test_deps = resolve(groups, "test")
print(f"Resolved 'test' group: {resolved_test_deps}")

# Resolve the 'build' dependency group
resolved_build_deps = resolve(groups, "build")
print(f"Resolved 'build' group: {resolved_build_deps}")

view raw JSON →