pypa/pip · error · InstallationError

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

Error message

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

What it means

InstallationError raised by the legacy resolver's _add_requirement_to_set when a direct wheel file (.whl) in the requirements is not compatible with the current platform's tags. pip builds a Wheel from the filename, computes compatibility_tags.get_supported() for the running interpreter/OS/arch, and if Wheel.supported(tags) is False (and check_supported_wheels is enabled) it refuses the wheel.

Source

Thrown at src/pip/_internal/resolution/legacy/resolver.py:232

        """
        # If the markers do not match, ignore this requirement.
        if not install_req.match_markers(extras_requested):
            logger.info(
                "Ignoring %s: markers '%s' don't match your environment",
                install_req.name,
                install_req.markers,
            )
            return [], None

        # If the wheel is not supported, raise an error.
        # Should check this after filtering out based on environment markers to
        # allow specifying different wheels based on the environment/OS, in a
        # single requirements file.
        if install_req.link and install_req.link.is_wheel:
            wheel = Wheel(install_req.link.filename)
            tags = compatibility_tags.get_supported()
            if requirement_set.check_supported_wheels and not wheel.supported(tags):
                raise InstallationError(
                    f"{wheel.filename} is not a supported wheel on this platform."
                )

        # This next bit is really a sanity check.
        assert (
            not install_req.user_supplied or parent_req_name is None
        ), "a user supplied req shouldn't have a parent"

        # Unnamed requirements are scanned again and the requirement won't be
        # added as a dependency until after scanning.
        if not install_req.name:
            requirement_set.add_unnamed_requirement(install_req)
            return [install_req], None

        try:
            existing_req: InstallRequirement | None = requirement_set.get_requirement(
                install_req.name
            )

View on GitHub (pinned to d7d0d0a394)

Solutions

Install a wheel matching your platform: check 'pip -V' and pick a wheel whose tags match (CPython version, OS, arch).
If only an sdist is available, let pip build from source: 'pip install foo==1.0' (no explicit wheel).
Upgrade Python to match the wheel's ABI, or rebuild the wheel on your platform ('pip wheel .').
If you knowingly need force, confirm the tags via 'pip debug --verbose' before retrying.

Example fix

# before — on Python 3.10/macOS arm64
pip install ./foo-1.0-cp39-cp39-manylinux1_x86_64.whl

# after
pip install foo==1.0   # let pip pick a compatible wheel or build from sdist

Defensive patterns

Strategy: validation

Validate before calling

from pip._internal.models.wheel import Wheel
from pip._internal.utils.compatibility_tags import get_supported
def wheel_supported_on_platform(filename: str) -> bool:
    return Wheel(filename).supported(get_supported())

Type guard

def is_platform_compatible_wheel(filename: str) -> bool:
    return wheel_supported_on_platform(filename)

Try / catch

if not wheel_supported_on_platform('foo-1.0-cp39-cp39-manylinux1_x86_64.whl'):
    print('wheel incompatible; install from sdist or matching wheel')
else:
    run_pip(['install', './foo-1.0-cp39-cp39-manylinux1_x86_64.whl'])

Prevention

Match wheel tags to your interpreter/OS/arch; inspect with 'pip debug --verbose'.
Prefer letting pip choose the wheel over pinning a specific .whl filename.
In cross-platform lockfiles, tag wheels per-platform and select at install time.

When it happens

Trigger: 'pip install ./foo-1.0-cp39-cp39-manylinux1_x86_64.whl' on, say, Python 3.10 / macOS / aarch64. The filename's tags (cp39, manylinux1, x86_64) do not intersect the supported tags, so supported() returns False.

Common situations: Downloading a wheel built for a different CPython ABI (cp39 vs cp310), a different OS (manylinux vs macosx), or a different architecture (x86_64 vs arm64); cross-platform lockfiles; CI matrix mismatch.

Related errors

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