pypa/pip · error · SidecarMetadataInconsistent

Requested {ireq} has inconsistent Provides-Extra between its

Error message

Requested {ireq} has inconsistent Provides-Extra between its PEP 658 .metadata file and the wheel's METADATA: sidecar has {f_val!r}, wheel has {m_val!r}

What it means

Raised as SidecarMetadataInconsistent for Provides-Extra when the set of declared extras in the PEP 658 .metadata sidecar differs from the wheel's METADATA. At prepare.py:331-339 both sides are turned into frozensets via iter_provided_extras(); the message reports extras present on one side but not the other.

Source

Thrown at src/pip/_internal/operations/prepare.py:334

        raise SidecarMetadataInconsistent(
            req,
            "Requires-Dist",
            ", ".join(sorted(sidecar_requires - wheel_requires)),
            ", ".join(sorted(wheel_requires - sidecar_requires)),
        )

    if sidecar_dist.requires_python != wheel_dist.requires_python:
        raise SidecarMetadataInconsistent(
            req,
            "Requires-Python",
            str(sidecar_dist.requires_python),
            str(wheel_dist.requires_python),
        )

    sidecar_extras = frozenset(sidecar_dist.iter_provided_extras())
    wheel_extras = frozenset(wheel_dist.iter_provided_extras())
    if sidecar_extras != wheel_extras:
        raise SidecarMetadataInconsistent(
            req,
            "Provides-Extra",
            ", ".join(sorted(sidecar_extras - wheel_extras)),
            ", ".join(sorted(wheel_extras - sidecar_extras)),
        )


class RequirementPreparer:
    """Prepares a Requirement"""

    def __init__(
        self,
        *,
        build_dir: str,
        download_dir: str | None,
        src_dir: str,
        build_isolation: BuildIsolationMode,
        build_isolation_installer: BuildEnvironmentInstaller,

View on GitHub (pinned to d7d0d0a394)

Solutions

Clear pip and HTTP caches: pip cache purge, then retry.
Install from the official index with the exact version pinned to avoid stale sidecar data.
Avoid requesting the extra that is inconsistent, or use a version known to declare it consistently: pip install 'pkg==<ver>[extra]'.
Report to the index operator to regenerate .metadata files on wheel changes.

Example fix

# before: sidecar has no 'docs' extra, wheel METADATA does
pip install 'pkg[docs]'  # -> SidecarMetadataInconsistent Provides-Extra

# after: use official index, exact version
pip install --index-url https://pypi.org/simple/ 'pkg==1.0.0[docs]'

Defensive patterns

Strategy: validation

Validate before calling

def extras_match(sidecar_extras, wheel_extras) -> bool:
    return frozenset(sidecar_extras) == frozenset(wheel_extras)

if not extras_match(sidecar.iter_provided_extras(), wheel.iter_provided_extras()):
    logger.warning("extras differ between sidecar and wheel")

Type guard

def extras_match(sidecar: list[str], wheel: list[str]) -> bool:
    return frozenset(sidecar) == frozenset(wheel)

Prevention

Pin exact versions and extras from a trusted index.
Regenerate .metadata files whenever the extras set changes.
Purge caches when consistency errors first appear.

When it happens

Trigger: The sidecar advertises a different set of extras (e.g. 'test', 'docs') than the wheel's METADATA. Triggered in _check_sidecar_matches_wheel after a remote wheel is fully downloaded.

Common situations: A release added/removed an extra but the index's .metadata sidecar is stale. Mirror/CDN desync. Re-published wheel with changed extras.

Related errors

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