{"record":{"id":"9551fc15dea25808","repo":"pypa/pip","slug":"wheel-filename-is-not-a-supported-wheel-for-this","errorCode":null,"errorMessage":"{wheel.filename} is not a supported wheel for this platform. It can't be sorted.","messagePattern":"(.+?) is not a supported wheel for this platform\\. It can't be sorted\\.","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/index/package_finder.py","lineNumber":561,"sourceCode":"              comparison operators, but then different sdist links\n              with the same version, would have to be considered equal\n        \"\"\"\n        valid_tags = self._supported_tags\n        support_num = len(valid_tags)\n        build_tag: BuildTag = ()\n        binary_preference = 0\n        link = candidate.link\n        if link.is_wheel:\n            # can raise InvalidWheelFilename\n            wheel = Wheel(link.filename)\n            try:\n                pri = -(\n                    wheel.find_most_preferred_tag(\n                        valid_tags, self._wheel_tag_preferences\n                    )\n                )\n            except ValueError:\n                raise UnsupportedWheel(\n                    f\"{wheel.filename} is not a supported wheel for this platform. It \"\n                    \"can't be sorted.\"\n                )\n            if self._prefer_binary:\n                binary_preference = 1\n            build_tag = wheel.build_tag\n        else:  # sdist\n            pri = -(support_num)\n        has_allowed_hash = int(link.is_hash_allowed(self._hashes))\n        yank_value = -1 * int(link.is_yanked)  # -1 for yanked.\n        return (\n            has_allowed_hash,\n            yank_value,\n            binary_preference,\n            candidate.version,\n            pri,\n            build_tag,\n        )","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/index/package_finder.py#L543-L579","documentation":"Raised by PackageFinder's candidate sorter (_sort_key) when a wheel filename's tags do not match any of the currently-supported platform/python/ABI tags. Wheel.find_most_preferred_tag() returns a ValueError when none of the wheel's compatibility tags intersect the environment's valid tags, which pip then wraps as UnsupportedWheel. The wheel cannot be ranked and is therefore unusable on this platform.","triggerScenarios":"Resolving a requirement where the only available wheel was built for a different Python version (e.g. cp39 on a cp311 interpreter), a different OS (Windows wheel on Linux), a different architecture (x86_64 vs arm64), or an incompatible ABI. pip's candidate sorter hits this while ranking available files.","commonSituations":"Installing a package with no pure-python or source distribution and only platform-specific wheels for another OS/arch; running under a different Python minor version than the wheels available; constrained platforms like Apple Silicon or aarch64 where wheels are scarce; pinning to an old Python where newer wheels are incompatible.","solutions":["Switch to a Python version / platform for which a compatible wheel exists (check the package's 'Download files' on PyPI).","Install from the source distribution instead (pip will build it if build deps are available), e.g. `pip install --no-binary :all: <pkg>`.","Upgrade pip, which may recognize newer wheel tag formats and have broader compatibility.","If a compatible wheel exists but pip isn't finding it, check --python-version, --platform, --only-binary, and --abi flags for cross-environment resolution.","For maintainers, build and upload wheels for the target platform (manylinux, macosx, etc.)."],"exampleFix":"# before (only macOS x86_64 wheels, running on arm64)\npip install <pkg>\n# after (force build from source)\npip install --no-binary <pkg> <pkg>\n# or target a compatible python/platform\npip install --python-version 3.11 --only-binary :all: --platform macosx_11_0_arm64 <pkg>","handlingStrategy":"fallback","validationCode":"from pip._vendor.packaging.tags import sys_tags\nfrom pip._internal.utils.compatibility_tags import Wheel\n\ndef wheel_compatible(wheel_filename: str) -> bool:\n    w = Wheel(wheel_filename)\n    valid = {(t.interpreter, t.abi, t.platform) for t in sys_tags()}\n    return any((w.pyver, w.abi, w.plat) in valid for _ in [0])\n","typeGuard":null,"tryCatchPattern":"import subprocess\ntry:\n    subprocess.run(['pip', 'install', '--only-binary', ':all:', pkg], check=True)\nexcept subprocess.CalledProcessError:\n    # no compatible wheel; fall back to building from source\n    subprocess.run(['pip', 'install', '--no-binary', pkg, pkg], check=True)\n","preventionTips":["Match your Python version/OS/arch to available wheels on PyPI before installing.","Keep pip updated for broader wheel-tag compatibility.","Have build toolchains ready as a fallback for packages without compatible wheels.","Use --python-version/--platform/--abi for cross-environment resolution."],"tags":["pip","wheel","platform","compatibility","architecture"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}