pypa/pip · error · UnsupportedWheel

WHEEL is missing Wheel-Version

Error message

WHEEL is missing Wheel-Version

What it means

UnsupportedWheel raised by wheel_version when the parsed WHEEL metadata message has no Wheel-Version header at all. The Wheel-Version field is mandatory in wheel metadata (it declares the wheel spec major.minor). Its absence means the WHEEL file is incomplete or malformed.

Source

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

    try:
        wheel_text = wheel_contents.decode()
    except UnicodeDecodeError as e:
        raise UnsupportedWheel(f"error decoding {path!r}: {e!r}")

    # FeedParser (used by Parser) does not raise any exceptions. The returned
    # 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

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Inspect: `unzip -p pkg.whl '*/WHEEL'` and confirm a `Wheel-Version:` line is present.
2. Rebuild with a standard PEP 517 backend which always emits Wheel-Version.
3. Re-download from a trusted index and verify the hash.
4. Run `twine check` to catch this before install.

Example fix

// before
# WHEEL file contained only 'Generator: mybuilder\n'
pip install pkg-1.0-py3-none-any.whl

// after
# rebuild; backend emits:
#   Wheel-Version: 1.0
rm -rf dist && python -m build --wheel

import zipfile, email.parser
def wheel_has_version(path: str) -> bool:
    with zipfile.ZipFile(path) as z:
        entry = next((n for n in z.namelist() if n.endswith('/WHEEL')), None)
        if not entry:
            return False
        msg = email.parser.Parser().parsestr(z.read(entry).decode('utf-8'))
        return msg['Wheel-Version'] is not None

null

null

When it happens

Trigger: wheel_version accesses wheel_data['Wheel-Version']; if the Message has no such header it returns None and this error fires. Happens when a hand-written or third-party-tool-generated WHEEL file omits the field.

Common situations: Custom backend that doesn't emit Wheel-Version; tampered wheel where the header was stripped; an empty WHEEL file.

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}
• invalid Wheel-Version: {version!r}

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