{"id":"6027f72c97cf3e94","repo":"pypa/pip","slug":"missing-metadata-version","errorCode":null,"errorMessage":"Missing Metadata-Version","messagePattern":"Missing Metadata-Version","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/wheel_builder.py","lineNumber":109,"sourceCode":"\ndef _verify_one(req: InstallRequirement, wheel_path: str) -> None:\n    canonical_name = canonicalize_name(req.name or \"\")\n    w = Wheel(os.path.basename(wheel_path))\n    if w.name != canonical_name:\n        raise InvalidWheelFilename(\n            f\"Wheel has unexpected file name: expected {canonical_name!r}, \"\n            f\"got {w.name!r}\",\n        )\n    dist = get_wheel_distribution(FilesystemWheel(wheel_path), canonical_name)\n    dist_verstr = str(dist.version)\n    if canonicalize_version(dist_verstr) != canonicalize_version(w.version):\n        raise InvalidWheelFilename(\n            f\"Wheel has unexpected file name: expected {dist_verstr!r}, \"\n            f\"got {w.version!r}\",\n        )\n    metadata_version_value = dist.metadata_version\n    if metadata_version_value is None:\n        raise UnsupportedWheel(\"Missing Metadata-Version\")\n    try:\n        metadata_version = Version(metadata_version_value)\n    except InvalidVersion:\n        msg = f\"Invalid Metadata-Version: {metadata_version_value}\"\n        raise UnsupportedWheel(msg)\n    if metadata_version >= Version(\"1.2\") and not isinstance(dist.version, Version):\n        raise UnsupportedWheel(\n            f\"Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} is not\"\n        )\n\n\ndef _build_one(\n    req: InstallRequirement,\n    output_dir: str,\n    verify: bool,\n    editable: bool,\n) -> str | None:\n    \"\"\"Build one wheel.","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/wheel_builder.py#L91-L127","documentation":"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`.","triggerScenarios":"`_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.","commonSituations":"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.","solutions":["Rebuild the wheel with a standard compliant backend (setuptools, hatchling, flit, pdm-backend) which always emits `Metadata-Version`.","Inspect `dist/*.whl`'s `*.dist-info/METADATA` and confirm the `Metadata-Version:` line is present (e.g. `2.1`).","If you produced the wheel manually, add `Metadata-Version: 2.1` to METADATA and regenerate.","Discard the bad wheel from any cache (pip wheel cache) to avoid reuse."],"exampleFix":"# before (METADATA missing Metadata-Version)\nMetadata-Version:\nName: mypkg\nVersion: 1.0.0\n\n# after\nMetadata-Version: 2.1\nName: mypkg\nVersion: 1.0.0","handlingStrategy":"validation","validationCode":"import zipfile, os\n\ndef wheel_has_metadata_version(wheel_path: str) -> bool:\n    with zipfile.ZipFile(wheel_path) as z:\n        meta = next(n for n in z.namelist() if n.endswith(\".dist-info/METADATA\"))\n        with z.open(meta) as f:\n            for line in f:\n                if line.decode(\"utf-8\").startswith(\"Metadata-Version:\"):\n                    return True\n    return False","typeGuard":"null","tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\ntry:\n    _verify_one(req, wheel_path)\nexcept UnsupportedWheel as e:\n    if str(e) == \"Missing Metadata-Version\":\n        # rebuild with a compliant backend\n        ...","preventionTips":["Use a PEP 517 compliant backend (setuptools/hatchling/flit) which always emits Metadata-Version.","If assembling wheels manually, include `Metadata-Version: 2.1` in METADATA.","Validate wheels with `twine check dist/*` before publishing."],"tags":["wheel","packaging","metadata","spec-compliance"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}