pypa/pip · error · SidecarMetadataInconsistent

Requested has inconsistent Name between its PEP 658…

Error message

Requested {ireq} has inconsistent Name 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 by _check_sidecar_matches_wheel (prepare.py:298) as SidecarMetadataInconsistent. PEP 658 lets an index publish a separate .metadata sidecar file so resolvers can read dependencies without downloading the wheel; that sidecar MUST be byte-identical to the wheel's METADATA for the Name field. pip enforces this and aborts on a Name mismatch to prevent the resolver from planning against different metadata than what actually installs.

Solutions

Report the mismatch to the index/mirror operator — the sidecar and wheel are out of sync server-side.
Switch to a different index or PyPI directly to confirm the package is intact upstream.
Clear local caches (pip cache purge) and retry to rule out a locally cached bad sidecar.
If you publish the package, rebuild and re-upload the wheel so the .metadata sidecar is regenerated consistently.

Example fix

# before
pip install --index-url https://broken-mirror/simple/ pkg
# after: use canonical PyPI
pip install --index-url https://pypi.org/simple/ pkg

Defensive patterns

Strategy: validation

Validate before calling

# Compare a downloaded PEP 658 .metadata sidecar Name against the wheel METADATA Name before installing.
from email.parser import Parser
import zipfile, requests

def sidecar_name_matches(wheel_url: str, sidecar_url: str) -> bool:
    wheel = requests.get(wheel_url).content
    name_w = Parser().parsestr(
        zipfile.ZipFile(__import__('io').BytesIO(wheel))
        .read(next(n for n in zipfile.ZipFile(__import__('io').BytesIO(wheel)).namelist()
                   if n.endswith('.dist-info/METADATA'))).decode()
    )['Name']
    name_s = Parser().parsestr(requests.get(sidecar_url).text)['Name']
    return name_s == name_w

Type guard

from pip._vendor.packaging.utils import canonicalize_name

def names_match(sidecar_name: str, wheel_name: str) -> bool:
    return canonicalize_name(sidecar_name) == canonicalize_name(wheel_name)

Try / catch

# Verify against an alternate index before trusting a mirror.
from subprocess import run
run(["pip", "install", "--no-cache-dir", "-i", "https://pypi.org/simple/", pkg], check=True)

Prevention

Prefer the official PyPI for reproducibility; treat custom mirrors as untrusted for metadata.
Purge pip cache when seeing sidecar mismatches to rule out stale local copies.
If you operate an index, invalidate/regenerate PEP 658 sidecars on every re-upload.

When it happens

Trigger: The index/mirror served a PEP 658 .metadata file whose Name: field canonicalizes differently from the Name in the downloaded wheel's METADATA. Occurs during _fetch_metadata_using_link_data_attr when the sidecar is downloaded and compared to the wheel.

Common situations: A misconfigured private index/mirror that caches stale sidecar metadata after a package was republished/re-signed; a CDN serving a mismatched .metadata; metadata regeneration bugs in the index software.

Related errors

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

Appendix: source

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

) -> None:
    """Check that a .metadata-based distribution matches the wheel's METADATA.

    Compare ``Name``, ``Version``, ``Requires-Dist``, ``Requires-Python``
    and ``Provides-Extra`` between the two and abort the install on any
    mismatch as PEP 658 requires the metadata files "MUST be identical".

    While the PEP doesn't mandate that consumers enforce the identical
    requirement, it's good nonetheless to check to prevent confusing
    behaviour when an index misbehaves.

    Also note for name and version, pip usually rejects wheels if they're
    inconsistent already. Checking them again here is purely defensive.
    """

    sidecar_name = canonicalize_name(sidecar_dist.raw_name)
    wheel_name = canonicalize_name(wheel_dist.raw_name)
    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,

View on GitHub (pinned to f399c37189)