pypa/pip · error · SidecarMetadataInconsistent

Requested {ireq} 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 as SidecarMetadataInconsistent for the Name field when the canonicalized project name in a PEP 658 .metadata sidecar differs from the name in the downloaded wheel's METADATA. PEP 658 requires the sidecar to be identical to the wheel METADATA; this check at prepare.py:296-299 enforces it to prevent a misbehaving index from causing confusing dependency resolution.

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 d7d0d0a394)

Solutions

  1. Clear the local download cache and pip cache: pip cache purge, then retry.
  2. Switch to the canonical index: pip install --index-url https://pypi.org/simple/ <pkg>.
  3. Pin the exact wheel by hash/URL so pip does not rely on the sidecar metadata.
  4. If you operate the index, ensure .metadata files are regenerated whenever the wheel is updated.

Example fix

# before: index serves mismatched sidecar
pip install pkg  # -> SidecarMetadataInconsistent Name

# after: bypass sidecar via direct wheel URL with hash
pip install https://files.pythonhosted.org/.../pkg-1.0-py3-none-any.whl --require-hashes
Defensive patterns

Strategy: fallback

Validate before calling

from pip._vendor.packaging.utils import canonicalize_name
# compare sidecar name vs wheel METADATA name before relying on resolution
if canonicalize_name(sidecar_name) != canonicalize_name(wheel_name):
    logger.warning("sidecar/wheel name mismatch; falling back to direct wheel")

Type guard

from pip._vendor.packaging.utils import canonicalize_name
def names_match(a: str, b: str) -> bool:
    return canonicalize_name(a) == canonicalize_name(b)

Prevention

When it happens

Trigger: An index serves a .metadata file whose Name field canonicalizes differently from the wheel's actual METADATA Name. Occurs during _check_sidecar_matches_wheel after the wheel is fully downloaded and only for remote wheels where a metadata_link() was used.

Common situations: A misconfigured or compromised package index, a caching proxy that served a stale/mismatched .metadata file, or a mirror that is mid-sync. Very rare on PyPI proper.

Related errors

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