pypa/pip · error · InstallationError

[dependency-groups] resolution failed for

Error message

[dependency-groups] resolution failed for '{groupname}' from '{path}': {'; '.join(messages)}

What it means

pip's dependency-group resolver (DependencyGroupResolver.resolve()) raised an ExceptionGroup while resolving a specific group name. This happens when the group contains invalid PEP 508 entries or references another group (via include-group) that does not exist. All sub-exception messages are joined into one InstallationError.

Solutions

1. Read the joined messages in the error — each sub-exception names the specific failing entry
2. Verify every include-group reference points to a group that exists in the same [dependency-groups] table
3. Validate each string entry with packaging.requirements.Requirement() to find the malformed one
4. Check for circular references between groups (A includes B, B includes A)

Example fix

# before — pyproject.toml
[dependency-groups]
test = ["pytest", { include-group = "lint-nonexistent" }]

# after
[dependency-groups]
test = ["pytest", { include-group = "lint" }]
lint = ["ruff"]

from pip._vendor.packaging.dependency_groups import DependencyGroupResolver
from pip._vendor.packaging.errors import ExceptionGroup

def validate_group_resolution(raw_groups: dict, groupname: str) -> bool:
    try:
        resolver = DependencyGroupResolver(raw_groups)
        list(resolver.resolve(groupname))
        return True
    except Exception:
        return False

from pip._vendor.packaging.dependency_groups import DependencyGroupResolver

def is_resolvable_group(raw_groups: dict, groupname: str) -> bool:
    """Type guard: True if the group resolves without error."""
    try:
        resolver = DependencyGroupResolver(raw_groups)
        list(resolver.resolve(groupname))
        return True
    except Exception:
        return False

from pip._internal.exceptions import InstallationError
from pip._internal.req.req_dependency_group import parse_dependency_groups

try:
    reqs = parse_dependency_groups([("pyproject.toml", groupname)])
except InstallationError as e:
    logger.error("Group resolution failed: %s", e)
    # inspect joined messages for specifics, fix entries, retry

When it happens

Trigger: Running 'pip install --group mygroup' where mygroup contains an entry like 'nonexistent-group' (referenced via include-group but not defined), or contains a string that is not valid PEP 508. The resolver collects all failures into an ExceptionGroup.

Common situations: Group references with typos. Circular group references. Entries that are plain strings with bad syntax. Groups defined in one pyproject.toml but referenced from another where they don't exist.

Related errors

• [dependency-groups] table was missing from
• not found. Cannot resolve '--group' option.
• [dependency-groups] data was invalid in
• [dependency-groups] table was malformed in
• Error parsing

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/fd7d6b14e0d018cd. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/req/req_dependency_group.py:35

    resolvers = _build_resolvers(path for (path, _) in groups)
    return list(_resolve_all_groups(resolvers, groups))


def _resolve_all_groups(
    resolvers: dict[str, DependencyGroupResolver], groups: list[tuple[str, str]]
) -> Iterator[str]:
    """
    Run all resolution, converting any error from `DependencyGroupResolver` into
    an InstallationError.
    """
    for path, groupname in groups:
        resolver = resolvers[path]
        try:
            yield from (str(req) for req in resolver.resolve(groupname))
        except ExceptionGroup as eg:
            # Convert ExceptionGroup to a single InstallationError with all messages
            messages = [str(e) for e in eg.exceptions]
            raise InstallationError(
                f"[dependency-groups] resolution failed for '{groupname}' "
                f"from '{path}': {'; '.join(messages)}"
            ) from eg


def _build_resolvers(paths: Iterable[str]) -> dict[str, Any]:
    resolvers = {}
    for path in paths:
        if path in resolvers:
            continue

        pyproject = _load_pyproject(path)
        if "dependency-groups" not in pyproject:
            raise InstallationError(
                f"[dependency-groups] table was missing from '{path}'. "
                "Cannot resolve '--group' option."
            )
        raw_dependency_groups = pyproject["dependency-groups"]

View on GitHub (pinned to f399c37189)