python-poetry/poetry · error · RuntimeError

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

Error message

{wheel.filename} is not a supported wheel for this platform. It can't be sorted.

What it means

Raised by Chooser._sort_key at src/poetry/installation/chooser.py:298-302 when link.is_wheel is True but Wheel(link.filename).is_supported_by_environment(self._env) returns False. Poetry refuses to even rank an incompatible wheel, surfacing the mismatch explicitly. RuntimeError.

Source

Thrown at src/poetry/installation/chooser.py:299

        Second, excepting hash considerations, candidates that have been
        yanked (in the sense of PEP 592) are always less preferred than
        candidates that haven't been yanked. Then:
        If not finding wheels, they are sorted by version only.
        If finding wheels, then the sort order is by version, then:
          1. existing installs
          2. wheels ordered via Wheel.support_index_min(self._supported_tags)
          3. source archives
        If prefer_binary was set, then all wheels are sorted above sources.
        Note: it was considered to embed this logic into the Link
              comparison operators, but then different sdist links
              with the same version, would have to be considered equal
        """
        build_tag: tuple[Any, ...] = ()
        binary_preference = 0
        if link.is_wheel:
            wheel = Wheel(link.filename)
            if not wheel.is_supported_by_environment(self._env):
                raise RuntimeError(
                    f"{wheel.filename} is not a supported wheel for this platform. It "
                    "can't be sorted."
                )

            # TODO: Binary preference
            pri = -(wheel.get_minimum_supported_index(self._env.supported_tags) or 0)
            if wheel.build_tag is not None:
                match = re.match(r"^(\d+)(.*)$", wheel.build_tag)
                if not match:
                    raise ValueError(f"Unable to parse build tag: {wheel.build_tag}")
                build_tag_groups = match.groups()
                build_tag = (int(build_tag_groups[0]), build_tag_groups[1])
        else:  # sdist
            support_num = len(self._env.supported_tags)
            pri = -support_num

        has_allowed_hash = int(self._is_link_hash_allowed_for_package(link, package))

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Confirm the active environment: `poetry env info` and check Python version/platform.
2. Switch to an env matching the wheel: `poetry env use python3.11` (or the relevant interpreter).
3. If the wheel is genuinely incompatible and shouldn't be listed, report it to the repository maintainer or restrict the source.
4. Prefer sources that also ship an sdist so Poetry can build for the current platform.

Example fix

# before: poetry running under python3.9, package only has cp311 wheels
$ poetry install
RuntimeError: pkg-1.0-cp311-...whl is not a supported wheel...

# after
$ poetry env use python3.11
$ poetry install

from poetry.utils.env import EnvManager
from poetry.installation.wheel import Wheel

env = EnvManager.get_default_env()
wheel = Wheel(link.filename)
if not wheel.is_supported_by_environment(env):
    raise ValueError(f'{link.filename} incompatible with env {env.marker_env}')

def wheel_supported(filename: str, env) -> bool:
    from poetry.installation.wheel import Wheel
    return Wheel(filename).is_supported_by_environment(env)

try:
    chooser._get_links(package)
except RuntimeError as e:
    if 'not a supported wheel' in str(e):
        # switch env or restrict candidates
        raise SystemExit('Switch to a compatible interpreter via `poetry env use`.') from e
    raise

When it happens

Trigger: The candidate set includes a wheel whose tags (Python ABI, platform) do not match the target env — e.g. a cp39-manylinux wheel considered under a cp311-win32 interpreter. Triggered during install/update sorting when at least one link is a wheel.

Common situations: Wrong-platform wheel listed in the index (rare, but happens with mirrored legacy repos), an env mismatch ( Poetry running under a different Python than intended), or a transitive dependency that only ships platform wheels for other OSes.

Related errors

• Package {link.url} cannot be installed in the current enviro
• Unable to parse build tag: {wheel.build_tag}
• Attempting to write {path} outside of the target directory T
• This project requires Poetry {version_constraint}, but you a
• Unknown metadata version: {dist.metadata_version}

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/20c15285e5594440.json. Report an issue: GitHub.