pypa/pip · error · SidecarMetadataInconsistent

Requested {ireq} has inconsistent Requires-Dist between its

Error message

Requested {ireq} has inconsistent Requires-Dist 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 Requires-Dist when the set of canonicalized dependencies in the PEP 658 .metadata sidecar differs from those in the wheel's METADATA. At prepare.py:311-321 both sides are canonicalized via _canonical_requires and compared as frozensets; the message shows the symmetric difference (sidecar-only vs wheel-only) to avoid noise from matching entries.

Source

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

    if sidecar_name != wheel_name:
        raise SidecarMetadataInconsistent(req, "Name", sidecar_name, wheel_name)

    if sidecar_dist.version != wheel_dist.version:
        raise SidecarMetadataInconsistent(
            req,
            "Version",
            str(sidecar_dist.version),
            str(wheel_dist.version),
        )

    # For multi-use fields, only report the symmetric difference to avoid
    # unnecessarily flagging matching values.
    sidecar_requires = _canonical_requires(
        req, sidecar_dist, "the PEP 658 .metadata file"
    )
    wheel_requires = _canonical_requires(req, wheel_dist, "the wheel's METADATA")
    if sidecar_requires != wheel_requires:
        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(

View on GitHub (pinned to d7d0d0a394)

Solutions

Clear caches: pip cache purge and flush any fronting HTTP cache, then retry.
Reinstall against the official index pinned to the exact version: pip install --index-url https://pypi.org/simple/ 'pkg==<ver>'.
Compare the sidecar .metadata and the wheel METADATA Requires-Dist lines directly to confirm the mismatch is on the index side, not local.
Report to the index operator so they regenerate .metadata files.

Example fix

# before: sidecar lists 'numpy>=1', wheel METADATA lists 'numpy>=1.20'
pip install pkg  # -> SidecarMetadataInconsistent Requires-Dist

# after: use official index, exact version, no sidecar reliance
pip install --index-url https://pypi.org/simple/ 'pkg==1.0.0'

Defensive patterns

Strategy: validation

Validate before calling

from pip._internal.operations.prepare import _canonicalize_requirement
from pip._vendor.packaging.requirements import InvalidRequirement

def canonical_requires(lines):
    out = set()
    for raw in lines:
        try:
            out.add(_canonicalize_requirement(raw.strip()))
        except InvalidRequirement as e:
            raise ValueError(f"bad Requires-Dist {raw!r}: {e}")
    return frozenset(out)

if canonical_requires(sidecar_requires) != canonical_requires(wheel_requires):
    print("dependency sets differ; do not trust sidecar")

Prevention

Use a trusted index and pin exact versions to avoid stale dependency sidecars.
Regenerate .metadata files whenever dependencies change on a self-hosted index.
Purge caches on first occurrence.

When it happens

Trigger: The dependency list advertised in the sidecar .metadata file doesn't match the wheel's actual dependencies after canonicalization (name casing, extras ordering, specifier differences). Triggered in _check_sidecar_matches_wheel for remote wheels.

Common situations: Index serves a stale .metadata after a release that changed dependencies. Mirror desync. A re-published wheel whose deps changed but .metadata wasn't regenerated.

Related errors

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