pypa/pip · error · UnsupportedWheel

is not a supported wheel on this platform.

Error message

{link.filename} is not a supported wheel on this platform.

What it means

_fail_if_link_is_unsupported_wheel (factory.py:134-141) in the new (resolvelib) resolver checks a link's wheel tags against the finder's target_python.get_unsorted_tags(); if none match it raises UnsupportedWheel. Same platform-compatibility guard as the legacy resolver but applied when the resolvelib factory builds candidates from links.

Solutions

Use a wheel whose tags match your platform/Python/ABI.
Build from sdist so pip compiles a compatible wheel.
Set --platform, --abi, and --python-version together to match the target when doing offline/cross-platform resolution.

Example fix

# before
pip install https://index.example.com/pkg-1.0-cp36-win_amd64.whl   # on Linux
# after
pip install pkg==1.0   # let resolver pick a Linux wheel

Defensive patterns

Strategy: validation

Validate before calling

# Verify a link's wheel is supported before passing it to the resolver.
from pip._internal.utils.compatibility_tags import get_supported
from pip._internal.utils.wheel import Wheel
import sys
link_file = sys.argv[1]
w = Wheel(link_file)
assert w.supported(get_supported()), f"{link_file} unsupported on this platform"
print("OK")

Prevention

Publish wheels for all target platforms in your index.
When cross-targeting, pass matching --platform/--abi/--python-version.
Provide sdists as a fallback so pip can build locally.

When it happens

Trigger: The new resolver encounters a wheel link (from an index or direct URL) whose tags don't intersect the target platform's supported tags.

Common situations: Wrong-platform wheel on PyPI or a private index; --platform/--abi/--python-version target flags inconsistent with available wheels; cross-target installs.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/resolution/resolvelib/factory.py:141

            self._installed_dists = {
                dist.canonical_name: dist
                for dist in env.iter_installed_distributions(local_only=False)
            }
        else:
            self._installed_dists = {}

    @property
    def force_reinstall(self) -> bool:
        return self._force_reinstall

    def _fail_if_link_is_unsupported_wheel(self, link: Link) -> None:
        if not link.is_wheel:
            return
        wheel = Wheel(link.filename)
        if wheel.supported(self._finder.target_python.get_unsorted_tags()):
            return
        msg = f"{link.filename} is not a supported wheel on this platform."
        raise UnsupportedWheel(msg)

    def _make_extras_candidate(
        self,
        base: BaseCandidate,
        extras: frozenset[str],
        *,
        comes_from: InstallRequirement | None = None,
    ) -> ExtrasCandidate:
        cache_key = (id(base), frozenset(canonicalize_name(e) for e in extras))
        try:
            candidate = self._extras_candidate_cache[cache_key]
        except KeyError:
            candidate = ExtrasCandidate(base, extras, comes_from=comes_from)
            self._extras_candidate_cache[cache_key] = candidate
        return candidate

    def _make_candidate_from_dist(
        self,

View on GitHub (pinned to f399c37189)