pypa/pip · error · UnsupportedWheel

's Wheel-Version ( ) is not compatible with this version of…

Error message

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

What it means

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.)

Solutions

  1. Upgrade pip to the latest version: 'python -m pip install --upgrade pip'
  2. If you cannot upgrade pip, find an older wheel of the same package compatible with wheel format 1.x
  3. Pin to a package version that ships format-1 wheels
  4. In a virtualenv, recreate it with the latest pip: 'python -m venv --upgrade-deps .venv'

Example fix

// before
# old pip encountering a wheel-version-2 wheel
pip install newformat-pkg==2.0
// after
python -m pip install --upgrade pip
pip install newformat-pkg==2.0
Defensive patterns

Strategy: validation

Validate before calling

import zipfile, subprocess, sys
from email.parser import Parser

def pip_supports_wheel(wheel_path: str) -> bool:
    pip_version = subprocess.check_output([sys.executable, '-m', 'pip', '--version'], text=True)
    # heuristic: pip >= 23 supports wheel spec 1.0; for 2.x you need a future pip
    with zipfile.ZipFile(wheel_path) as zf:
        for name in zf.namelist():
            if name.endswith('.dist-info/WHEEL'):
                msg = Parser().parsestr(zf.read(name).decode())
                v = msg['Wheel-Version']
                if v:
                    major = int(v.strip().split('.')[0])
                    return major <= 1  # pip currently supports spec 1.x
    return True

Type guard

def is_compatible_wheel_version(version: tuple[int, ...], supported: tuple[int, ...] = (1, 0)) -> bool:
    return version[0] <= supported[0]

Try / catch

from pip._internal.exceptions import UnsupportedWheel

try:
    check_compatibility(version, name)
except UnsupportedWheel as e:
    if 'not compatible' in str(e):
        # upgrade pip and retry
        raise UpgradeRequiredError(f'upgrade pip to install this wheel: {e}')
    raise

Prevention

When it happens

Trigger: Calling check_compatibility(version, name) where version[0] > VERSION_COMPATIBLE[0] (i.e. > 1). Reached during wheel installation after the version is successfully parsed.

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

Related errors

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

Appendix: 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 f399c37189)