Error "filename.whl is not a supported wheel on this platform"

Decoding wheel file name and system specs

The primary step when encountering this error is to slice and dice the filename and your system's specs like a coding Ninja. The wheel naming follows this pattern: package-version-cpXY-none/abi3/platform.whl where XY should match with your Python version.

Firing up your pip

To validate different wheel files effectively, pimp your pip by upgrading it:

# Who said Python developers don't upgrade?
python -m pip install --upgrade pip


This simple step is often a panacea for compatibility issues, as fresh pip versions have enhanced wheel file handling powers.

Checking Python's architecture

win32 or win_amd64, that is the question. If you're unsure whether your Python is 32-bit or 64-bit, run this command:

# The Python whisperer says your architecture is...
python -c "import struct;print(8 * struct.calcsize('P'))"


It returns 32 or 64, indicating your Python's architecture which should be in line with the wheel file's tag.

Hunting for wheels in the wild

Should you find the official PyPI lacks the right wheel, try the unofficial Windows binaries by Christoph Gohlke:

http://www.lfd.uci.edu/~gohlke/pythonlibs/

These Python-package-laden pages are a potential paradise for Windows users questing for the right binaries.

Bringing in the heavy tools - Building from source

If the wheel gods aren't favoring your platform, descend into the source's depths by building the package from the source:

pip install --no-binary :all: package_name
# Especially helpful when the wheel makers are on holiday


This tells pip to pull up its sleeves and compile the package, instead of lazily looking for a pre-built wheel.

Behind the scenes - Pip's debug output

When it all goes south, draw on pip's verbose options and channel your inner Sherlock Holmes:

pip install your_package.whl -v
# More verbose than your garrulous grandma!


The detailed feedback could unveil why pip brushes off the wheel as a non-fit.

Avoiding rookie mistakes - check your filename

Ensure your wheel filename is typo-free and makes sense. Even typos, small errors, or inappropriate versions in filename might bring about the annoying error.

If an upgrade doesn't bother you, bring your Python version up to speed with the latest release, so you're aligned with the package dynamics. The latest Python releases play well with most modern packages.