pypa/pip · error · UnsupportedWheel

invalid Wheel-Version

Error message

invalid Wheel-Version: {version!r}

What it means

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.

Solutions

  1. Inspect the Wheel-Version value: 'unzip -p <file>.whl "*.dist-info/WHEEL" | grep Wheel-Version'
  2. Rebuild the wheel with a compliant build backend
  3. Ensure the WHEEL file uses a numeric major.minor format like '1.0'
  4. Re-download from the official PyPI index

Example fix

// before
Wheel-Version: 1.0-dev
// after
Wheel-Version: 1.0
Defensive patterns

Strategy: validation

Validate before calling

from email.parser import Parser
import zipfile

def wheel_version_is_numeric(path: str) -> bool:
    with zipfile.ZipFile(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 is None:
                    return False
                try:
                    tuple(map(int, v.strip().split('.')))
                    return True
                except ValueError:
                    return False
    return False

Type guard

def is_numeric_version(version_text: str) -> bool:
    try:
        all(int(p) for p in version_text.strip().split('.'))
        return True
    except ValueError:
        return False

Try / catch

from pip._internal.exceptions import UnsupportedWheel

try:
    wheel_version(metadata)
except UnsupportedWheel as e:
    if 'invalid Wheel-Version' in str(e):
        raise PackagingError(f'fix WHEEL file to use numeric version: {e}')
    raise

Prevention

When it happens

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

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

Related errors

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

Appendix: source

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

    # message may have .defects populated, but for backwards-compatibility we
    # currently ignore them.
    return Parser().parsestr(wheel_text)


def wheel_version(wheel_data: Message) -> tuple[int, ...]:
    """Given WHEEL metadata, return the parsed Wheel-Version.
    Otherwise, raise UnsupportedWheel.
    """
    version_text = wheel_data["Wheel-Version"]
    if version_text is None:
        raise UnsupportedWheel("WHEEL is missing Wheel-Version")

    version = version_text.strip()

    try:
        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)))

View on GitHub (pinned to f399c37189)