{"record":{"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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/utils/wheel.py#L106-L133","documentation":"Raised by check_compatibility() when the wheel's major Wheel-Version is greater than pip's supported VERSION_COMPATIBLE (currently 1.0). A major version ahead means the wheel uses a format this pip cannot safely install. (A minor-only difference, e.g. 1.1 vs 1.0, only triggers a warning.)","triggerScenarios":"Calling check_compatibility(version, name) where version[0] > VERSION_COMPATIBLE[0] (i.e. > 1). Reached during wheel installation after the version is successfully parsed.","commonSituations":"A future wheel format (version 2.x+) is used by the wheel but the installed pip is too old. The Python packaging ecosystem has advanced to a new wheel spec major version. pip is outdated on the system or in a CI image.","solutions":["Upgrade pip to the latest version: 'python -m pip install --upgrade pip'","If you cannot upgrade pip, find an older wheel of the same package compatible with wheel format 1.x","Pin to a package version that ships format-1 wheels","In a virtualenv, recreate it with the latest pip: 'python -m venv --upgrade-deps .venv'"],"exampleFix":"// before\n# old pip encountering a wheel-version-2 wheel\npip install newformat-pkg==2.0\n// after\npython -m pip install --upgrade pip\npip install newformat-pkg==2.0","handlingStrategy":"validation","validationCode":"import zipfile, subprocess, sys\nfrom email.parser import Parser\n\ndef pip_supports_wheel(wheel_path: str) -> bool:\n    pip_version = subprocess.check_output([sys.executable, '-m', 'pip', '--version'], text=True)\n    # heuristic: pip >= 23 supports wheel spec 1.0; for 2.x you need a future pip\n    with zipfile.ZipFile(wheel_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:\n                    major = int(v.strip().split('.')[0])\n                    return major <= 1  # pip currently supports spec 1.x\n    return True","typeGuard":"def is_compatible_wheel_version(version: tuple[int, ...], supported: tuple[int, ...] = (1, 0)) -> bool:\n    return version[0] <= supported[0]","tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\n\ntry:\n    check_compatibility(version, name)\nexcept UnsupportedWheel as e:\n    if 'not compatible' in str(e):\n        # upgrade pip and retry\n        raise UpgradeRequiredError(f'upgrade pip to install this wheel: {e}')\n    raise","preventionTips":["Keep pip up to date: 'python -m pip install --upgrade pip'","Pin to package versions that ship wheel-format-1 artifacts if you cannot upgrade pip","In CI/Docker, use 'python -m venv --upgrade-deps' or a recent base image","Check the wheel format before installing from a cutting-edge source"],"tags":["wheel","wheel-version","compatibility","upgrade","installation"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}