More information about *why* a wheel is not supported on a given platform

[NAThompson]

What's the problem this feature will solve?

I maintain a set of wheel files with Python extension modules. Hence the binaries are Python version intolerant, OS version intolerant, and CPU architecture intolerant. I do not maintain all combinations of all platforms, Python versions, and CPU architecture.

Hence I often receive the following bug report:

ERROR: foo-1.2.0-cp39-cp39-macosx_12_0_x86_64.whl is not a supported wheel on this platform.

I have identified five separate causes for this error:

• Using pip associated with python3.8 (wrong interpreter)
• Trying to installing on Linux (wrong OS)
• Trying to installing on MacOS Big Sur, instead of Monterrey (wrong OS version)
• Trying to installing on M1 (wrong CPU architecture)
• Trying to install a debug wheel with a release Python virtualenv (wrong debug)

Describe the solution you'd like

When the error is reported, it would be helpful to be given information about why the wheel is unsupported. For example,

$ python3.8 -m pip install  foo-1.2.0-cp39-cp39-macosx_12_0_x86_64.whl

Should yield the following error:

ERROR: Wheel file `foo-1.2.0-cp39-cp39-macosx_12_0_x86_64.whl` requires Python3.9, but attempting to install it with Python3.8.

If the architecture is M1, then

$ python3.9 -m pip install  foo-1.2.0-cp39-cp39-macosx_12_0_x86_64.whl

should yield the error

ERROR: Wheel file foo-1.2.0-cp39-cp39-macosx_12_0_x86_64.whl targets x86, but this platform is ARM.

Alternative Solutions

I have not tried alternative solutions; moreover I confess that this might be a feature request against wheel.

Additional context

This stackoverflow post shows that other people would also like to know why a wheel is not supported.

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[NAThompson]

I have attempted to implement this. The code is still rather inelegant:

#!/usr/bin/env python3
import argparse
from pathlib import Path
import sys
from packaging.utils import parse_wheel_filename
import platform


def diagnose_unsupported(p: Path) -> str:
    p = Path(p)
    if not p.exists():
        return f"File '{p}' does not exist"
    if not p.is_file():
        return f"'{p}' is not a file"
    if p.suffix != ".whl":
        return f"'{p}' has incorrect suffix; the suffix must be .whl"

    # The wheel filename must parse:
    _, _, _, tags = parse_wheel_filename(p.name)

    tag = None
    for t in tags:
        tag = t

    # Is a debug wheel being loaded in a non-debug interpreter?
    if tag.abi.endswith("d"):
        if not sys.flags.debug:
            return f"The ABI of the wheel is {tag.abi}, which is a debug wheel. However, the python interpeter does not have the debug flags set."
    # Is a cpython wheel being loaded by a non-cpython interpreter?
    if tag.abi.startswith("cp"):
        if sys.implementation.name != "cpython":
            return f"The ABI of the wheel '{p}' requires cpython, but the system implementation is {sys.implementation.name}"

    # If the interpreter is version intolerant, what interpreter should it be using?
    idx = tag.interpreter.find("3")
    if idx >= 0 and idx < len(tag.interpreter) - 1:
        supported_minor = int(tag.interpreter[idx + 1])
        if sys.version_info.minor != supported_minor:
            return f"The python minor version is {sys.version_info.minor}, but the wheel only supports minor version {supported_minor}"

    # There should be no restriction on the platform:
    if tag.platform == "any":
        return ""
    pieces = tag.platform.split("_")
    if len(pieces) != 4:
        print("Unable to parse the platform tag")

    wheel_os_name = pieces[0]
    wheel_os_version_major = pieces[1]
    wheel_os_version_minor = pieces[2]
    cpu_architecture = pieces[3]
    if wheel_os_name == "macosx":
        if sys.platform != "darwin":
            return f"The wheel was build for macosx, but the current platform is {sys.platform}"

    if cpu_architecture != platform.machine():
        return f"The CPU architecture supported by the wheel is {cpu_architecture}, but the platform has architecture {platform.machine()}"

    os_major, os_minor, os_patch = platform.mac_ver()[0].split(".")
    if int(os_major) < int(wheel_os_version_major):
        return f"The operating system major version is {os_major}, but the wheel requires at least OS major version {wheel_os_version_major}"
    if int(os_major) == int(wheel_os_version_major):
        if int(os_minor) < int(wheel_os_version_minor):
            return f"The operating system minor version is {os_minor}, but the wheel requires at least OS major version {wheel_os_version_minor}"

    return ""


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Diagnoses why a wheel is unsupported on a particular platform."
    )
    parser.add_argument("wheelfile", type=Path, help="The name of the wheel file.")
    args = parser.parse_args()
    error_msg = diagnose_unsupported(args.wheelfile)
    if len(error_msg) > 0:
        print(
            f"ERROR: {args.wheelfile} is not supported on this platform. Reason: {error_msg}"
        )
    else:
        print(f"{args.wheelfile} should be supported on your platform!")

[uranusjr]

Maybe this can build on #9708?

[picnic-sven]

Bumping this for visibility, since it would be nice to give more information to a user why a certain wheel (supposedly) can't be installed.

[uranusjr]

Pull requests are always welcomed.

[abhi-glitchhg]

+1 for this.

One more case that i encountered was when we use links to download wheels from internet with pip; and if the link is broken then also we get the same message. I know passing broken links to pip install command doesnt make much sense; but it would help if the message is more verbose.

[stellarpower]

I have attempted to implement this. The code is still rather inelegant:

https://gist.github.com/stellarpower/d0cc9d57b8b79fe6a6344f376a4fa8f8https://gist.github.com/stellarpower/d0cc9d57b8b79fe6a6344f376a4fa8f8

I've modified to return more than one reason where those apply. Rather quickly and brute-force, so there may be bugs in the logic by not returning early.

[jbvsmo]

+1 This change would be very welcome

[MichaelVoelkel]

Yes!!

[murthyn]

+1

[ruckc]

I'd love this because I just compiled a wheel with the same python version on the same machine as i'm trying to install it on.

[pfmoore]

Please do not simply add "+1" or "me too" comments to this issue. It's awaiting someone willing to provide a pull request for it, and such comments won't help get it implemented. If you want to express support for the idea, add a "thumbs up" reaction to the original post. That will indicate your support without spamming the maintainers and others already watching this issue.

[ssbarnea]

Something even stranger seems to be happening with this check:

ssbarnea@u1:~/u/vscode-ansible vscode-ansible (main) $ pip uninstall ruamel.yaml.clib
Found existing installation: ruamel.yaml.clib 0.2.8
Uninstalling ruamel.yaml.clib-0.2.8:
  Would remove:
    /home/ssbarnea/.local/share/virtualenvs/vsa/lib/python3.12/site-packages/_ruamel_yaml.cpython-312-aarch64-linux-gnu.so
    /home/ssbarnea/.local/share/virtualenvs/vsa/lib/python3.12/site-packages/ruamel.yaml.clib-0.2.8.dist-info/*
Proceed (Y/n)? y
  Successfully uninstalled ruamel.yaml.clib-0.2.8
ssbarnea@u1:~/u/vscode-ansible vscode-ansible (main) $ pip install ruamel.yaml.clib
Collecting ruamel.yaml.clib
  Using cached ruamel.yaml.clib-0.2.8-cp312-cp312-manylinux_2_24_aarch64.whl.metadata (2.2 kB)
Using cached ruamel.yaml.clib-0.2.8-cp312-cp312-manylinux_2_24_aarch64.whl (643 kB)
Installing collected packages: ruamel.yaml.clib
Successfully installed ruamel.yaml.clib-0.2.8
ssbarnea@u1:~/u/vscode-ansible vscode-ansible (main) $ pip check
ruamel.yaml.clib 0.2.8 is not supported on this platform

For some reason pip finds and installs successfully the wheel but it breaks pip check, and because we do run pip check in CI, now we have a broken build.

Note: Ubuntu 24.04 on arm64. Also reported on https://sourceforge.net/p/ruamel-yaml/tickets/521/ as I am not sure yet where it originates from.

Update: it might be caused by #12884

[g-kartik]

I tried downloading wheels in a multi state stage Dockerfile in the build stage. But when trying to install in the final runtime stage, it fails giving an error that those wheels are not supported on this platform.
Both build and run time stages use Ubuntu 20.04 as the base image. Both have python 3.8 installed. What can be the issue?

[danielhollas]

@g-kartik you'll probably have more luck opening a new issue and providing more concrete information, ideally a minimal reproducible Dockerfile, and content of the WHEEL file in the *.whl archive.