pypa/pip · error · UnsupportedWheel

invalid Wheel-Version: {version!r}

Error message

invalid Wheel-Version: {version!r}

What it means

UnsupportedWheel raised when the Wheel-Version header is present but cannot be parsed into a tuple of integers. After stripping, pip does tuple(map(int, version.split('.'))); a ValueError (non-numeric components) is wrapped with the offending version string repr. The wheel spec requires a numeric Major.Minor version.

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

Solutions

1. Inspect: `unzip -p pkg.whl '*/WHEEL' | grep Wheel-Version`.
2. Set Wheel-Version to a plain numeric value like '1.0'.
3. Rebuild with a standard backend.
4. Run `twine check` before install.

Example fix

// before
# WHEEL: Wheel-Version: 1.0-beta
pip install pkg-1.0-py3-none-any.whl

// after
# WHEEL: Wheel-Version: 1.0
rm -rf dist && python -m build --wheel

import zipfile, email.parser
def wheel_version_parses(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'))
    v = (msg['Wheel-Version'] or '').strip()
    try:
        tuple(map(int, v.split('.')))
        return True
    except ValueError:
        return False

null

null

When it happens

Trigger: wheel_version sees a Wheel-Version like '1.0rc1', 'v1.0', '1.a', or '' and int() fails on a component.

Common situations: Hand-written WHEEL with a non-numeric version; tooling that appended a suffix; tampering; backend bug.

Related errors

• {name} has an invalid wheel, {e}
• multiple .dist-info directories found: {}
• .dist-info directory {info_dir!r} does not start with {canon
• error decoding {path!r}: {e!r}
• WHEEL is missing Wheel-Version

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