pypa/pip · error · UnsupportedWheel

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

Error message

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

What it means

UnsupportedWheel raised by _fail_if_link_is_unsupported_wheel when a candidate link is a .whl but Wheel(link.filename).supported(tags) is false — the wheel's platform/python/ABI tags do not match the target interpreter. pip will not install a wheel it knows it cannot use.

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

Solutions

1. Let pip pick the wheel: don't hardcode a specific .whl filename, use the project name and version specifier.
2. Upgrade pip on the target so it understands the newer manylinux/macosx tags.
3. Provide/source a wheel matching the target's tags (cp<ver>-cp<ver>-<plat>), or fall back to sdist build.
4. For cross-install, use the correct --python-version / --platform / --only-binary flags, or a separate matching environment.

Example fix

# before - pinned wrong-platform wheel filename
pip install "mypkg-1.0-cp39-cp39-win_amd64.whl"  # on linux py3.11

# after - let pip resolve the right wheel
pip install mypkg==1.0

from pip._internal.utils.compatibility_tags import Wheel

def wheel_matches_target(filename, target_python):
    w = Wheel(filename)
    return w.supported(target_python.get_unsorted_tags())
# check a pinned .whl filename against the target before adding it to a lock

try:
    pip_install(wheel_filename)
except UnsupportedWheel:
    pip_install(project_name)  # let pip pick a compatible wheel

When it happens

Trigger: link.is_wheel is True and wheel.supported(self._finder.target_python.get_unsorted_tags()) returns False. E.g. forcing install of a cp39-cp39-win_amd64 wheel on CPython 3.11 linux, or a macosx_11_0 arm64 wheel on x86_64 macOS, or a py2-none-any wheel under a tag set that excludes it.

Common situations: Wrong-architecture wheels on a slim CI image (e.g. pulling a Windows wheel on Linux); Apple Silicon vs Intel mismatch; pinning a wheel filename in a cross-platform constraints file; an index that only hosts a platform wheel none of your targets match.

Related errors

• No module named {module!r}
• Can not combine '--user' and '--target'
• Target path exists but is not a directory, will not continue
• failed-wheel-build-for-install
• Can not combine '--user' and '--prefix' as they imply differ

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