{"id":"340eebcbaefc3758","repo":"pypa/pip","slug":"link-filename-is-not-a-supported-wheel-on-this-p","errorCode":null,"errorMessage":"{link.filename} is not a supported wheel on this platform.","messagePattern":"(.+?) is not a supported wheel on this platform\\.","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/resolution/resolvelib/factory.py","lineNumber":141,"sourceCode":"            self._installed_dists = {\n                dist.canonical_name: dist\n                for dist in env.iter_installed_distributions(local_only=False)\n            }\n        else:\n            self._installed_dists = {}\n\n    @property\n    def force_reinstall(self) -> bool:\n        return self._force_reinstall\n\n    def _fail_if_link_is_unsupported_wheel(self, link: Link) -> None:\n        if not link.is_wheel:\n            return\n        wheel = Wheel(link.filename)\n        if wheel.supported(self._finder.target_python.get_unsorted_tags()):\n            return\n        msg = f\"{link.filename} is not a supported wheel on this platform.\"\n        raise UnsupportedWheel(msg)\n\n    def _make_extras_candidate(\n        self,\n        base: BaseCandidate,\n        extras: frozenset[str],\n        *,\n        comes_from: InstallRequirement | None = None,\n    ) -> ExtrasCandidate:\n        cache_key = (id(base), frozenset(canonicalize_name(e) for e in extras))\n        try:\n            candidate = self._extras_candidate_cache[cache_key]\n        except KeyError:\n            candidate = ExtrasCandidate(base, extras, comes_from=comes_from)\n            self._extras_candidate_cache[cache_key] = candidate\n        return candidate\n\n    def _make_candidate_from_dist(\n        self,","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/resolution/resolvelib/factory.py#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Let pip pick the wheel: don't hardcode a specific .whl filename, use the project name and version specifier.","Upgrade pip on the target so it understands the newer manylinux/macosx tags.","Provide/source a wheel matching the target's tags (cp<ver>-cp<ver>-<plat>), or fall back to sdist build.","For cross-install, use the correct --python-version / --platform / --only-binary flags, or a separate matching environment."],"exampleFix":"# before - pinned wrong-platform wheel filename\npip install \"mypkg-1.0-cp39-cp39-win_amd64.whl\"  # on linux py3.11\n\n# after - let pip resolve the right wheel\npip install mypkg==1.0","handlingStrategy":"validation","validationCode":"from pip._internal.utils.compatibility_tags import Wheel\n\ndef wheel_matches_target(filename, target_python):\n    w = Wheel(filename)\n    return w.supported(target_python.get_unsorted_tags())\n# check a pinned .whl filename against the target before adding it to a lock","typeGuard":null,"tryCatchPattern":"try:\n    pip_install(wheel_filename)\nexcept UnsupportedWheel:\n    pip_install(project_name)  # let pip pick a compatible wheel","preventionTips":["Don't hardcode .whl filenames in cross-platform requirements.","Upgrade pip on all targets so newer platform tags are recognized.","Use --only-binary/:all: with correct --platform/--python-version for cross-installs."],"tags":["pip","wheels","platform","tags","install"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}