pypa/pip · error · UnsupportedWheel

Missing Metadata-Version

Error message

Missing Metadata-Version

What it means

Raised by `_verify_one` when the built wheel's metadata has no `Metadata-Version` field at all (`dist.metadata_version is None`). `Metadata-Version` is a mandatory field in the wheel spec (it records which METADATA spec the distribution conforms to). Its absence means the wheel is malformed and pip cannot trust its metadata, so it raises `UnsupportedWheel`.

Source

Thrown at src/pip/_internal/wheel_builder.py:109

def _verify_one(req: InstallRequirement, wheel_path: str) -> None:
    canonical_name = canonicalize_name(req.name or "")
    w = Wheel(os.path.basename(wheel_path))
    if w.name != canonical_name:
        raise InvalidWheelFilename(
            f"Wheel has unexpected file name: expected {canonical_name!r}, "
            f"got {w.name!r}",
        )
    dist = get_wheel_distribution(FilesystemWheel(wheel_path), canonical_name)
    dist_verstr = str(dist.version)
    if canonicalize_version(dist_verstr) != canonicalize_version(w.version):
        raise InvalidWheelFilename(
            f"Wheel has unexpected file name: expected {dist_verstr!r}, "
            f"got {w.version!r}",
        )
    metadata_version_value = dist.metadata_version
    if metadata_version_value is None:
        raise UnsupportedWheel("Missing Metadata-Version")
    try:
        metadata_version = Version(metadata_version_value)
    except InvalidVersion:
        msg = f"Invalid Metadata-Version: {metadata_version_value}"
        raise UnsupportedWheel(msg)
    if metadata_version >= Version("1.2") and not isinstance(dist.version, Version):
        raise UnsupportedWheel(
            f"Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} is not"
        )


def _build_one(
    req: InstallRequirement,
    output_dir: str,
    verify: bool,
    editable: bool,
) -> str | None:
    """Build one wheel.

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Rebuild the wheel with a standard compliant backend (setuptools, hatchling, flit, pdm-backend) which always emits `Metadata-Version`.
2. Inspect `dist/*.whl`'s `*.dist-info/METADATA` and confirm the `Metadata-Version:` line is present (e.g. `2.1`).
3. If you produced the wheel manually, add `Metadata-Version: 2.1` to METADATA and regenerate.
4. Discard the bad wheel from any cache (pip wheel cache) to avoid reuse.

Example fix

# before (METADATA missing Metadata-Version)
Metadata-Version:
Name: mypkg
Version: 1.0.0

# after
Metadata-Version: 2.1
Name: mypkg
Version: 1.0.0

import zipfile, os

def wheel_has_metadata_version(wheel_path: str) -> bool:
    with zipfile.ZipFile(wheel_path) as z:
        meta = next(n for n in z.namelist() if n.endswith(".dist-info/METADATA"))
        with z.open(meta) as f:
            for line in f:
                if line.decode("utf-8").startswith("Metadata-Version:"):
                    return True
    return False

null

from pip._internal.exceptions import UnsupportedWheel
try:
    _verify_one(req, wheel_path)
except UnsupportedWheel as e:
    if str(e) == "Missing Metadata-Version":
        # rebuild with a compliant backend
        ...

When it happens

Trigger: `_verify_one` reads `dist.metadata_version` from the wheel's `*.dist-info/METADATA` and gets `None`. Triggered for wheels produced by broken/non-compliant build backends, hand-rolled wheels, or wheels whose METADATA file was truncated/corrupted.

Common situations: Custom or experimental build backends that omit `Metadata-Version`; wheels assembled by hand or by ad-hoc scripts that did not emit a full METADATA file; filesystem corruption truncating the METADATA file; very old third-party wheels predating the METADATA spec.

Related errors

• Wheel has unexpected file name: expected {canonical_name!r},
• Invalid Metadata-Version: {metadata_version_value}
• Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} i
• Invalid project name: {filename!r}
• Bad metadata in {dist} (invalid metadata entry 'name')

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