pypa/pip · error · UnsupportedWheel

{wheel.filename} is not a supported wheel for this platform.

Error message

{wheel.filename} is not a supported wheel for this platform. It can't be sorted.

What it means

UnsupportedWheel raised in LinkComparer._candidate_sort_key when a wheel filename parses structurally but none of its tags match any platform/python/abi tag the current interpreter supports (wheel.find_most_preferred_tag raises ValueError). The wheel is therefore unrankable and cannot be selected for installation.

Source

Thrown at src/pip/_internal/index/package_finder.py:561

              comparison operators, but then different sdist links
              with the same version, would have to be considered equal
        """
        valid_tags = self._supported_tags
        support_num = len(valid_tags)
        build_tag: BuildTag = ()
        binary_preference = 0
        link = candidate.link
        if link.is_wheel:
            # can raise InvalidWheelFilename
            wheel = Wheel(link.filename)
            try:
                pri = -(
                    wheel.find_most_preferred_tag(
                        valid_tags, self._wheel_tag_preferences
                    )
                )
            except ValueError:
                raise UnsupportedWheel(
                    f"{wheel.filename} is not a supported wheel for this platform. It "
                    "can't be sorted."
                )
            if self._prefer_binary:
                binary_preference = 1
            build_tag = wheel.build_tag
        else:  # sdist
            pri = -(support_num)
        has_allowed_hash = int(link.is_hash_allowed(self._hashes))
        yank_value = -1 * int(link.is_yanked)  # -1 for yanked.
        return (
            has_allowed_hash,
            yank_value,
            binary_preference,
            candidate.version,
            pri,
            build_tag,
        )

View on GitHub (pinned to d7d0d0a394)

Solutions

Use a wheel matching your interpreter: correct CPython version (cpXY), ABI, and platform tags (use 'pip debug --verbose' to list compatible tags).
Force a source build by removing --only-binary / loosening --no-binary so pip falls back to the sdist.
Upgrade the package to a version that ships wheels for your platform.
If building for another target, use the right interpreter/ABI (e.g. the embedded Python) rather than the system one.

Example fix

# before - wrong platform wheel selected
pip install somepkg  # cp39 wheel, you run cp311

# after
pip install --no-binary=:all: somepkg   # build from sdist
# or upgrade to a release with cp311 wheels
pip install -U somepkg

Defensive patterns

Strategy: validation

Validate before calling

from pip._internal.utils.compatibility_tags import get_supported
tags = get_supported()
from pip._internal.models.wheel import Wheel
w = Wheel('somepkg-1.0-cp39-cp39-manylinux1_x86_64.whl')
try:
    w.find_most_preferred_tag(tags, tags)
    print('compatible')
except ValueError:
    print('NOT compatible with this interpreter')

Type guard

def wheel_supported(filename: str) -> bool:
    from pip._internal.utils.compatibility_tags import get_supported
    from pip._internal.models.wheel import Wheel
    try:
        Wheel(filename).find_most_preferred_tag(get_supported(), get_supported())
        return True
    except (ValueError, Exception):
        return False

Try / catch

from pip._internal.exceptions import UnsupportedWheel
try:
    finder._candidate_sort_key(candidate)
except UnsupportedWheel as e:
    logger.info('skipping incompatible wheel: %s', e)

Prevention

Run 'pip debug --verbose' to see compatible tags before pinning wheels.
Allow sdist fallback (avoid --only-binary) for cross-platform robustness.
Pin wheels only for the exact target interpreter/ABI/platform.
Use 'pip index versions' to confirm wheel availability.

When it happens

Trigger: A candidate wheel whose tags (e.g. cp39-cp39-manylinux1_x86_64) do not intersect self._supported_tags for the running interpreter (e.g. CPython 3.11 on macOS arm64). Reached while sorting InstallationCandidate objects during dependency resolution.

Common situations: Trying to install a Linux-only wheel on macOS/Windows or vice versa; a cpXY wheel on a different CPython minor version; a platform wheel on PyPy; an old wheel with tags predating the current tagging scheme; a cross-architecture install (x86 wheel on arm64).

Related errors

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