pypa/pip · error · InstallationError

[dependency-groups] table was malformed in {path}. Cannot re

Error message

[dependency-groups] table was malformed in {path}. Cannot resolve '--group' option.

What it means

Raised by _build_resolvers() when a `[dependency-groups]` entry exists in pyproject.toml but is not a TOML table/dict (req_dependency_group.py:54). PEP 735 requires dependency-groups to be a mapping of group-name -> list-of-requirements; an array, string, or scalar at the top level is structurally invalid.

Source

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

                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"]
        if not isinstance(raw_dependency_groups, dict):
            raise InstallationError(
                f"[dependency-groups] table was malformed in {path}. "
                "Cannot resolve '--group' option."
            )

        try:
            resolvers[path] = DependencyGroupResolver(raw_dependency_groups)
        except ExceptionGroup as eg:
            # Handle ExceptionGroup from resolver initialization
            messages = [str(e) for e in eg.exceptions]
            raise InstallationError(
                f"[dependency-groups] data was invalid in {path}: {'; '.join(messages)}"
            ) from eg

    return resolvers


def _load_pyproject(path: str) -> dict[str, Any]:
    """

View on GitHub (pinned to d7d0d0a394)

Solutions

Restructure [dependency-groups] as a table whose keys are group names and whose values are arrays of requirement strings.
Reload/validate the TOML after editing.
Re-run `pip install --group <name>`.

Example fix

# before
[dependency-groups]
dev = ["pytest"]  # actually written as: dependency-groups = ["pytest"]
# after
[dependency-groups]
dev = ["pytest"]
test = ["pytest", "coverage"]

Defensive patterns

Strategy: validation

Validate before calling

import tomllib

def assert_dependency_groups_is_dict(path: str) -> None:
    with open(path, "rb") as f:
        data = tomllib.load(f)
    raw = data.get("dependency-groups")
    if not isinstance(raw, dict):
        raise TypeError(f"[dependency-groups] in {path} must be a table/dict, got {type(raw).__name__}")

Type guard

import tomllib

def is_dependency_groups_well_shaped(path: str) -> bool:
    with open(path, "rb") as f:
        raw = tomllib.load(f).get("dependency-groups")
    return isinstance(raw, dict)

Try / catch

null

Prevention

Author [dependency-groups] as a table: each key is a group name, each value an array of strings.
Lint pyproject.toml with validate-pyproject or a TOML schema checker.
Avoid flattening requirements directly under the dependency-groups key.

When it happens

Trigger: Writing `dependency-groups = ["pytest"]` (a flat array) instead of `dependency-groups = {dev = [...]}`. Or `dependency-groups = "dev"`. The isinstance(raw_dependency_groups, dict) check fails.

Common situations: Misunderstanding PEP 735's structure and listing requirements directly under the key. Copy-pasting from a non-conforming example. Tooling that emits the wrong shape.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/863b4fad3d277284.json. Report an issue: GitHub.