pypa/pip · error · UnsupportedWheel

{}'s Wheel-Version ({}) is not compatible with this version

Error message

{}'s Wheel-Version ({}) is not compatible with this version of pip

What it means

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.

Source

Thrown at src/pip/_internal/utils/wheel.py:124

        return tuple(map(int, version.split(".")))
    except ValueError:
        raise UnsupportedWheel(f"invalid Wheel-Version: {version!r}")


def check_compatibility(version: tuple[int, ...], name: str) -> None:
    """Raises errors or warns if called with an incompatible Wheel-Version.

    pip should refuse to install a Wheel-Version that's a major series
    ahead of what it's compatible with (e.g 2.0 > 1.1); and warn when
    installing a version only minor version ahead (e.g 1.2 > 1.1).

    version: a 2-tuple representing a Wheel-Version (Major, Minor)
    name: name of wheel or package to raise exception about

    :raises UnsupportedWheel: when an incompatible Wheel-Version is given
    """
    if version[0] > VERSION_COMPATIBLE[0]:
        raise UnsupportedWheel(
            "{}'s Wheel-Version ({}) is not compatible with this version "
            "of pip".format(name, ".".join(map(str, version)))
        )
    elif version > VERSION_COMPATIBLE:
        logger.warning(
            "Installing from a newer Wheel-Version (%s)",
            ".".join(map(str, version)),
        )

View on GitHub (pinned to d7d0d0a394)

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.

Example fix

// before
# wheel declares Wheel-Version: 2.0, pip only supports 1.x
pip install pkg-1.0-py3-none-any.whl

// after
python -m pip install --upgrade pip && pip install pkg==1.0

Defensive patterns

Strategy: validation

Validate before calling

import zipfile, email.parser
PIP_MAJOR = 1
def wheel_version_compatible(path: str) -> bool:
    with zipfile.ZipFile(path) as z:
        entry = next((n for n in z.namelist() if n.endswith('/WHEEL')), None)
        msg = email.parser.Parser().parsestr(z.read(entry).decode('utf-8'))
    version = tuple(map(int, (msg['Wheel-Version'] or '0').strip().split('.')))
    return version[0] <= PIP_MAJOR

Type guard

null

Try / catch

null

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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