pypa/pip · error · UnsupportedWheel

WHEEL is missing Wheel-Version

Error message

WHEEL is missing Wheel-Version

What it means

Raised by wheel_version() when the parsed WHEEL metadata message has no 'Wheel-Version' header. The Wheel-Version field is mandatory in the wheel format spec; its absence means the metadata file is incomplete or malformed.

Solutions

  1. Inspect the WHEEL file: 'unzip -p <file>.whl "*.dist-info/WHEEL"'
  2. Rebuild the wheel with a compliant build backend (setuptools, hatchling, flit)
  3. Ensure the WHEEL file contains 'Wheel-Version: 1.0'
  4. Re-download from the official PyPI index

Example fix

// before
# WHEEL file missing Wheel-Version line
Wheel-Version: 
Generator: custom
// after
Wheel-Version: 1.0
Generator: setuptools (68.0.0)
Root-Is-Purelib: true
Tag: py3-none-any
Defensive patterns

Strategy: validation

Validate before calling

import zipfile
from email.parser import Parser

def wheel_has_version(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())
                return msg['Wheel-Version'] is not None
    return False

Type guard

from email.message import Message

def has_wheel_version(metadata: Message) -> bool:
    return metadata.get('Wheel-Version') is not None

Try / catch

from pip._internal.exceptions import UnsupportedWheel

try:
    wheel_version(metadata)
except UnsupportedWheel as e:
    if 'missing Wheel-Version' in str(e):
        raise PackagingError(f'wheel metadata incomplete: {e}')
    raise

Prevention

When it happens

Trigger: Calling wheel_version(wheel_data) where wheel_data['Wheel-Version'] returns None. Reached during wheel installation via parse_wheel() after the WHEEL file is successfully read and decoded.

Common situations: A hand-authored or tool-generated WHEEL file missing the Wheel-Version line. A wheel built by a non-standard or experimental build backend. A corrupt or partially-written WHEEL file.

Related errors

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

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