ERROR pip platform_error ai_generated true

ERROR: <package>.whl is not a supported wheel on this platform.

ID: pip/platform-mismatch

Also available as: JSON · Markdown
82%Fix Rate
85%Confidence
50Evidence
2022-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
24 active — — —

Root Cause

The wheel file was built for a different platform (OS, architecture, or Python implementation). Common when downloading wheels from another machine, mixing x86_64/aarch64, or using glibc wheels on musl (Alpine).

generic

Workarounds

  1. 88% success Install directly from PyPI to get the correct platform wheel 
    pip install <package> (without specifying a local wheel file)
  2. 82% success Build from source for the current platform 
    pip install --no-binary <package> <package>
  3. 85% success Check compatible tags and download the right wheel: pip debug --verbose 
    Run pip debug --verbose to see supported tags, then download a wheel matching one of those tags

Dead Ends

Common approaches that don't work:

  1. Rename the wheel file to match current platform tags 90% fail

    The wheel contains compiled binaries for the original platform; renaming does not recompile them and will cause runtime crashes

  2. Use --force-reinstall with the incompatible wheel 95% fail

    Force-reinstall does not override platform compatibility checks; pip still rejects the wheel

Error Chain

Leads to:
Preceded by:
Frequently confused with: