{"record":{"id":"52afb5c0571325bf","repo":"pypa/pip","slug":"invalid-wheel-version-version-r","errorCode":null,"errorMessage":"invalid Wheel-Version: {version!r}","messagePattern":"invalid Wheel-Version: (.+?)","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/wheel.py","lineNumber":108,"sourceCode":"    # message may have .defects populated, but for backwards-compatibility we\n    # currently ignore them.\n    return Parser().parsestr(wheel_text)\n\n\ndef wheel_version(wheel_data: Message) -> tuple[int, ...]:\n    \"\"\"Given WHEEL metadata, return the parsed Wheel-Version.\n    Otherwise, raise UnsupportedWheel.\n    \"\"\"\n    version_text = wheel_data[\"Wheel-Version\"]\n    if version_text is None:\n        raise UnsupportedWheel(\"WHEEL is missing Wheel-Version\")\n\n    version = version_text.strip()\n\n    try:\n        return tuple(map(int, version.split(\".\")))\n    except ValueError:\n        raise UnsupportedWheel(f\"invalid Wheel-Version: {version!r}\")\n\n\ndef check_compatibility(version: tuple[int, ...], name: str) -> None:\n    \"\"\"Raises errors or warns if called with an incompatible Wheel-Version.\n\n    pip should refuse to install a Wheel-Version that's a major series\n    ahead of what it's compatible with (e.g 2.0 > 1.1); and warn when\n    installing a version only minor version ahead (e.g 1.2 > 1.1).\n\n    version: a 2-tuple representing a Wheel-Version (Major, Minor)\n    name: name of wheel or package to raise exception about\n\n    :raises UnsupportedWheel: when an incompatible Wheel-Version is given\n    \"\"\"\n    if version[0] > VERSION_COMPATIBLE[0]:\n        raise UnsupportedWheel(\n            \"{}'s Wheel-Version ({}) is not compatible with this version \"\n            \"of pip\".format(name, \".\".join(map(str, version)))","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/utils/wheel.py#L90-L126","documentation":"Raised by wheel_version() when the Wheel-Version header value cannot be parsed into a tuple of integers. The version is split on '.' and each part must convert to int; a ValueError means the value contains non-numeric segments.","triggerScenarios":"Calling wheel_version(wheel_data) where version_text.strip().split('.') yields non-integer parts, e.g. '1.0a' or 'v1.0'. The int() conversion raises ValueError.","commonSituations":"A WHEEL file with a non-standard version string like '1.0-dev', 'v1', or '1.0a'. A hand-edited or corrupt WHEEL file. A build backend emitting a non-conformant version format.","solutions":["Inspect the Wheel-Version value: 'unzip -p <file>.whl \"*.dist-info/WHEEL\" | grep Wheel-Version'","Rebuild the wheel with a compliant build backend","Ensure the WHEEL file uses a numeric major.minor format like '1.0'","Re-download from the official PyPI index"],"exampleFix":"// before\nWheel-Version: 1.0-dev\n// after\nWheel-Version: 1.0","handlingStrategy":"validation","validationCode":"from email.parser import Parser\nimport zipfile\n\ndef wheel_version_is_numeric(path: str) -> bool:\n    with zipfile.ZipFile(path) as zf:\n        for name in zf.namelist():\n            if name.endswith('.dist-info/WHEEL'):\n                msg = Parser().parsestr(zf.read(name).decode())\n                v = msg['Wheel-Version']\n                if v is None:\n                    return False\n                try:\n                    tuple(map(int, v.strip().split('.')))\n                    return True\n                except ValueError:\n                    return False\n    return False","typeGuard":"def is_numeric_version(version_text: str) -> bool:\n    try:\n        all(int(p) for p in version_text.strip().split('.'))\n        return True\n    except ValueError:\n        return False","tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\n\ntry:\n    wheel_version(metadata)\nexcept UnsupportedWheel as e:\n    if 'invalid Wheel-Version' in str(e):\n        raise PackagingError(f'fix WHEEL file to use numeric version: {e}')\n    raise","preventionTips":["Use 'Wheel-Version: 1.0' (numeric major.minor) in WHEEL files","Build wheels with standard backends that emit conformant versions","Inspect WHEEL contents before installing or publishing","Avoid hand-editing the WHEEL file version field"],"tags":["wheel","metadata","wheel-version","packaging","installation"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}