{"id":"333ba15fcb4fe547","repo":"pypa/pip","slug":"s-wheel-version-is-not-compatible-with-thi","errorCode":null,"errorMessage":"{}'s Wheel-Version ({}) is not compatible with this version of pip","messagePattern":"(.+?)'s Wheel-Version \\((.+?)\\) is not compatible with this version of pip","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/wheel.py","lineNumber":124,"sourceCode":"        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)))\n        )\n    elif version > VERSION_COMPATIBLE:\n        logger.warning(\n            \"Installing from a newer Wheel-Version (%s)\",\n            \".\".join(map(str, version)),\n        )\n","sourceCodeStart":106,"sourceCodeEnd":133,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/utils/wheel.py#L106-L133","documentation":"UnsupportedWheel raised by check_compatibility when the wheel's major Wheel-Version is greater than the major pip understands (VERSION_COMPATIBLE = (1, 0), so any Wheel-Version 2.x or higher). pip can install minor-newer versions with a warning but refuses a major-series jump because the wheel format itself has changed in an incompatible way.","triggerScenarios":"Installing a wheel whose WHEEL metadata declares Wheel-Version 2.0+ on a pip that only implements spec version 1.x. Fires after version is parsed as (major, minor) and version[0] > 1.","commonSituations":"A future wheel spec (2.x) shipped before this pip supports it; downgrade pip on a system that already receives new-format wheels; a hand-edited WHEEL with a wrong major number.","solutions":["Upgrade pip to the latest release: `python -m pip install --upgrade pip`.","If you can't upgrade pip, install an older wheel of the package whose Wheel-Version is 1.x.","Confirm the WHEEL file isn't mislabeled: `unzip -p pkg.whl '*/WHEEL' | grep Wheel-Version`.","Rebuild with a backend matching the installed pip's wheel-spec support."],"exampleFix":"// before\n# wheel declares Wheel-Version: 2.0, pip only supports 1.x\npip install pkg-1.0-py3-none-any.whl\n\n// after\npython -m pip install --upgrade pip && pip install pkg==1.0","handlingStrategy":"validation","validationCode":"import zipfile, email.parser\nPIP_MAJOR = 1\ndef wheel_version_compatible(path: str) -> bool:\n    with zipfile.ZipFile(path) as z:\n        entry = next((n for n in z.namelist() if n.endswith('/WHEEL')), None)\n        msg = email.parser.Parser().parsestr(z.read(entry).decode('utf-8'))\n    version = tuple(map(int, (msg['Wheel-Version'] or '0').strip().split('.')))\n    return version[0] <= PIP_MAJOR","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Keep pip upgraded.","Install wheel versions matching your pip's spec support.","Don't hand-set Wheel-Version to a future major.","Use `twine check` and verify WHEEL metadata before install."],"tags":["pip","wheel","version","compatibility","upgrade"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}