{"id":1450,"library":"dependency-groups","title":"Dependency Groups (PEP 735 Implementation)","description":"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.","status":"active","version":"1.3.1","language":"python","source_language":"en","source_url":"https://github.com/pypa/dependency-groups","tags":["packaging","dependencies","pyproject.toml","PEP 735","tooling","development-dependencies"],"install":[{"cmd":"pip install dependency-groups","lang":"bash","label":"Core library"},{"cmd":"pip install \"dependency-groups[cli]\"","lang":"bash","label":"With CLI tools (includes tomli for older Pythons)"}],"dependencies":[{"reason":"Required for parsing pyproject.toml. Built-in Python 3.11+, explicit dependency for older Python versions (3.8-3.10) if installing `dependency-groups[cli]`.","package":"tomllib","optional":false}],"imports":[{"note":"A functional interface to resolve a dependency group to a list of strings.","symbol":"resolve","correct":"from dependency_groups import resolve"},{"note":"An object-oriented interface for more advanced resolution and inspection.","symbol":"DependencyGroupResolver","correct":"from dependency_groups import DependencyGroupResolver"}],"quickstart":{"code":"import tomllib\nimport io\nfrom dependency_groups import resolve\n\n# Simulate a pyproject.toml file content\npyproject_content = \"\"\"\n[dependency-groups]\ntest = [\"pytest\", {\"include-group\": \"runtime\"}]\nruntime = [\"flask\"]\nbuild = [\"build\", \"twine\"]\n\"\"\"\n\n# In a real project, you would load from 'pyproject.toml':\n# with open(\"pyproject.toml\", \"rb\") as fp:\n#     pyproject = tomllib.load(fp)\n# groups = pyproject[\"dependency-groups\"]\n\n# For quickstart, load from the string\npyproject = tomllib.load(io.BytesIO(pyproject_content.encode('utf-8')))\ngroups = pyproject[\"dependency-groups\"]\n\n# Resolve the 'test' dependency group\nresolved_test_deps = resolve(groups, \"test\")\nprint(f\"Resolved 'test' group: {resolved_test_deps}\")\n\n# Resolve the 'build' dependency group\nresolved_build_deps = resolve(groups, \"build\")\nprint(f\"Resolved 'build' group: {resolved_build_deps}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use distinct names for your dependency groups (in `[dependency-groups]`) and optional dependencies (in `[project.optional-dependencies]`) within your `pyproject.toml`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully structure your `include-group` declarations in `pyproject.toml` to ensure no circular dependencies exist between your groups.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For runtime optional features that users can install, use `project.optional-dependencies`. For core runtime dependencies, use `project.dependencies`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the test environment uses Python 3.11 or newer, or modify the test script to use the `tomli` backport for compatibility with older Python versions (e.g., `import tomli as tomllib` or conditionally import `tomli` if `tomllib` is unavailable).","message":"The test script or environment attempts to use `tomllib`, which is a standard library module introduced in Python 3.11. Running tests on Python versions older than 3.11 (e.g., Python 3.9) will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.3.1':43 '735':4,17,91 'activ':13 'author':50 'built':35 'current':40 'defin':20 'depend':1,8,56,71,86,88,95 'dependency-group':7 'develop':69,94 'development-depend':93 'development-tim':68 'distinguish':77 'document':76 'enabl':51 'face':85 'file':29 'group':2,9,57,61 'handl':59 'implement':5,14 'includ':33,58 'inclus':62 'librari':10,39 'like':72 'lint':74 'maintain':45 'mechan':22 'metadata':37 'nest':60 'option':82 'packag':25,49,87 'pars':52 'pep':3,16,90 'primarili':65 'project':36 'pyproject.toml':28,89 'python':48 'requir':26 'resolv':54 'runtim':80 'standard':19 'store':24 'test':73 'time':70 'tool':92 'use':66 'user':84 'user-fac':83 'version':42","created_at":"2026-04-09T03:48:27.613026+00:00","updated_at":"2026-04-16T06:12:51.728932+00:00","problems":[{"fix":"Run `pip install dependency-groups` to install the library.","cause":"The `dependency-groups` library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'dependency_groups'"},{"fix":"Ensure the `[dependency-groups]` table is at the top level of your `pyproject.toml` and contains valid TOML syntax for group names and dependency specifiers, e.g., `[dependency-groups]\ndocs = [\"sphinx\"]`.","cause":"The `[dependency-groups]` table or its contents are malformed, or it is incorrectly nested under a tool-specific table instead of being a top-level table.","error":"Error: Invalid TOML structure in pyproject.toml"},{"fix":"Review your `[dependency-groups]` definitions in `pyproject.toml` and break any circular `include-group` references.","cause":"You have defined a chain of `include-group` declarations in your `pyproject.toml` that forms a cycle (e.g., group A includes B, and B includes A), which is forbidden by PEP 735.","error":"DependencyGroupError: Cyclic dependency detected in group includes"},{"fix":"Adjust the version specifiers for the conflicting package(s) within your `[dependency-groups]` to ensure they are compatible, or specify the groups to be resolved separately if their dependencies are not intended to be compatible within the same environment.","cause":"When resolving multiple dependency groups or a group with project dependencies, incompatible version constraints were found for the same package, making a unified resolution impossible.","error":"ResolutionImpossible: Conflicting requirements found for dependencies across groups"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.1","cli_name":"dependency-groups","cli_version":"usage: dependency-groups [-h] [-f PYPROJECT_FILE] [-o OUTPUT] [-l]","type":"library","homepage":null,"github":"https://github.com/pypa/dependency-groups","docs":"https://dependency-groups.readthedocs.io/","changelog":"https://github.com/pypa/dependency-groups/blob/main/CHANGELOG.rst","pypi":"https://pypi.org/project/dependency-groups/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}