Error: filename.whl is not supported wheel on this platform

# Error: filename.whl is not supported wheel on this platform

The Python "ERROR: filename.whl is not a supported wheel on this platform" occurs for multiple reasons:

1. Trying to install a 32-bit .whl file with a 64-bit Python interpreter.
2. Trying to install a .whl file for a different Python version than the currently installed one.
3. Having a .whl file that is named incorrectly.
4. Having an outdated pip version.

# Make sure the .whl file is 64-bit if your Python interpreter is 64-bit

The first thing you should ensure is that the .whl file is 64-bit if your Python interpreter is 64-bit.

Similarly, if your .whl file is 32-bit, it can only be installed if your Python interpreter is 32-bit.

You can download 32-bit and 64-bit .whl files for most Python modules on this page.

First, check if your Python interpreter is 64-bit or 32-bit by issuing the following command in your shell (e.g. CMD).

Copied!
python -c "import sys; print(sys.maxsize > 2**32)"

# Or using py alias
py -c "import sys; print(sys.maxsize > 2**32)"

# Or using python3
python3 -c "import sys; print(sys.maxsize > 2**32)"

If you get a True value back, then your Python interpreter is 64-bit and you can only install 64-bit .whl files.

You can also check if your Python interpreter is 64-bit or 32-bit with the following Python script.

Copied!
import platform

print(platform.architecture())

Assuming you stored the script in a main.py file, you can run it with one of the following commands.

Copied!
python main.py

# Or with the `py` alias (Windows)
py main.py

# Or python3 (macOS and Linux)
python3 main.py

If you try to install a 32-bit .whl file on a 64-bit Python interpreter and vice versa, you would get the "filename.whl is not a supported wheel on this platform" error.

The name of the .whl file indicates whether it is 64-bit or 32-bit.

For example, numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl is 64-bit.

Notice that the filename ends with win_amd64, which means 64-bit.

And numpy‑1.22.4+vanilla‑cp310‑cp310‑win32.whl is 32-bit.

Note that the filename ends with win32 which means 32-bit.

If you aren't able to get a .whl file of the correct number of bits, you can try to rename the file that you have before running pip install.

For example, suppose that your Python interpreter is 64-bit but you have a 32-bit .whl file named numpy‑1.22.4+vanilla‑cp310‑cp310‑win32.whl.

You can try to rename the file as follows:

Copied!
# ⛔ Before (32-bit)
numpy‑1.22.4+vanilla‑cp310‑cp310‑win32.whl

# ✅ After (64-bit)
numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl

You can then rerun the pip install command.

Copied!
pip install numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl

There is no guarantee that the installation will succeed but it is worth a try.

Similarly, if you have a 32-bit Python interpreter and have a 64-bit .whl file, you can try to rename the file as follows.

Copied!
# ⛔️ Before (64-bit)
numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl

# ✅ After (32-bit)
numpy‑1.22.4+vanilla‑cp310‑cp310‑win32.whl

Then rerun the pip install command.

Copied!
pip install numpy‑1.22.4+vanilla‑cp310‑cp310‑win32.whl

# Check the supported tags on your system

You can also check the supported tags on your system by issuing the pip debug --verbose command.

Copied!
pip debug --verbose

The command will list all tags that are supported on your system.

The .whl file that you are installing has to match one of the supported tags.

# Make sure the version of the .whl file matches your Python version

Another common cause of the error is trying to install .whl file that requires one Python version on another Python version.

First, check your Python version by issuing one of the following commands.

Copied!
python --version

# Or with the `py` alias (Windows)
py --version

# Or python3 (macOS and Linux)
python3 --version

The screenshot shows that my Python version is 3.10, therefore the .whl file also has to have a version of 3.10.

You can check the Python version of a .whl file by looking at its name.

For example, numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl has a Python version of 3.10.

Notice that the filename contains cp310.

Similarly, the file numpy‑1.22.4+vanilla‑cp39‑cp39‑win_amd64.whl has a Python version of 3.9 because its name contains cp39.

The following file numpy‑1.16.6+mkl‑cp27‑cp27m‑win_amd64.whl has a Python version of 2.7 because its name contains cp27.

Your Python version has to match the Python version of the .whl file for the installation to succeed.

In many cases, you might be able to get around the error by changing the file's name.

For example, suppose you have a file named numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl (Python 3.10) but your Python version is 3.9.

In this case, you can try to change the Python version in the file's name to numpy‑1.22.4+vanilla‑cp39‑cp39‑win_amd64.whl.

In other words, cp39 instead of cp310.

Now you should be able to run the pip install command without running into any issues (assuming the package is 3.9 compatible).

Copied!
pip install numpy‑1.22.4+vanilla‑cp39‑cp39‑win_amd64.whl

Note that this approach wouldn't work if the package is not Python 3.9 compatible.

# Having a .whl file that is named incorrectly

You would also get the error if your .whl file is named incorrectly.

When you issue the pip install your-file.whl command, pip reads the name of your .whl file to determine if it should even attempt to install it.

It checks if the .whl file is 64-bit or 32-bit and if your Python interpreter matches.

If any of the conditions aren't met, pip will just raise the error without attempting to install the .whl file.

A very common cause of the error is having a (1) or (2) at the end of the filename due to downloading the same file multiple times.

For example, numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64 (1).whl.

Make sure to remove the (1) at the end because it prevents pip from being able to process the filename correctly.

Copied!
# ⛔️ change this
numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64 (1).whl

# ✅ to this
numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl

Make sure you don't have anything extra in your filename as this would prevent pip from parsing it correctly.

# A step-by-step guide on how to correctly install from a .whl file

Let's go through a step-by-step installation of a .whl file.

1. I will download a NumPy .whl file from this website.

My Python version is 3.10.

Copied!
python --version

# or py alias (Windows)
py --version

# or python (macOS and Linux)
python3 --version

And my Python interpreter is 64-bit.

Copied!
python -c "import sys; print(sys.maxsize > 2**32)"

# or using py alias
py -c "import sys; print(sys.maxsize > 2**32)"

# or using python3
python3 -c "import sys; print(sys.maxsize > 2**32)"

True = 64-bit and False = 32-bit.

Therefore, I have to download the following file:

• numpy‑1.22.4+vanilla‑cp310‑cp310‑win_amd64.whl

This is because cp310 means CPython version 3.10.

And win_amd64 means 64-bit Python interpreter.

In the unlikely case that your Python interpreter is 32-bit, you would be looking for win32 instead of win_amd64.

You can click on the link of the correct .whl file to download it.

I'm using https://www.lfd.uci.edu/~gohlke/pythonlibs/ for the example.

2. Once you download the correct .whl file, open your terminal in the directory in which the file is located.

3. Issue the pip install your-filename.whl command.

Copied!
pip install your-filename.whl

# or pip3
pip3 install your-filename.whl

# Try to upgrade your version of pip before running the pip install command

Another common cause of the error is having an outdated version of pip.

You can try to upgrade your version of pip by using one of the following 3 commands.

Copied!
python -m ensurepip --upgrade

# py alias (Windows)
py -m ensurepip --upgrade

# python3 (macOS and Linux)
python3 -m ensurepip --upgrade

If that doesn't work, try using the python -m command.

Copied!
python -m pip install --upgrade pip

# py alias (Windows)
py -m pip install --upgrade pip

# python3 (macOS and Linux)
python3 -m pip install --upgrade pip

If that doesn't work either, follow the instructions on how to upgrade pip in this article.

Once you've upgraded pip to the latest version, rerun your pip install command.

Copied!
pip install your-filename.whl

# or pip3
pip3 install your-filename.whl

# Conclusion

To solve the Python "ERROR: filename.whl is not a supported wheel on this platform" error, make sure:

1. The .whl file is 64-bit if your Python interpreter is 64-bit.
2. The version of the .whl file matches your Python version.
3. The .whl file is named correctly.
4. You don't have an outdated version of pip.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

• Check if Python is running as 32-bit or 64-bit
• ModuleNotFoundError: No module named 'pip' in Python
• Error: invalid command 'bdist_wheel' in Python [Solved]