How do I install a Python package with a .whl file?

Before you jump in

Before you proceed with installing your .whl file, there are a few prerequisites and checks to ensure a trouble-free installation.

Check your pip status

# Is pip feeling good today?
pip --version


If the above command returns an error, you might need to add pip to your PATH or navigate directly to your Scripts directory where pip.exe is located.

Know your wheel

Run this Python snippet to understand which wheel (.whl file tags) your system supports:

import pip   # "Importing pip, the Python package VIP"
print(pip.pep425tags.get_supported())


Download the .whl file variant that has a tag compatible with your system. For instance, if you're running CPython 3.9, grab the cp39 wheel.

Peek into the .whl file name

The name of the .whl file usually indicates its compatibility with different Python versions and system architectures (32-bit vs 64-bit). It's like reading the nutritional values on a food package!

One step at a time: The installation process

Ensure the wheel library

Just as a car needs wheels, installing .whl files needs the wheel library. So, let's install it:

# Like getting a tyre change for your car
pip install wheel


Direct installation

Now it's as simple as running:

# It's showtime!
pip install your_package.whl


Pointing to a directory

We're not always in the same directory as the .whl file. In that case, just feed the full path to our hungry pip:

# Feeding pip with the directory breadcrumb trail
pip install C:/path_to_your_file/your_package.whl


Offline or local directory installation

Think of --use-wheel and --no-index as GPS coordinates for installation from a local directory:

# "Alexa, take me to /your_directory and install my .whl file"
pip install --use-wheel --no-index --find-links=/your_directory your_package.whl


In case of cache troubles

The --no-cache-dir flag comes to your rescue when your cache decides to play hide and seek:

# Because sometimes, cache forgets to cherish
pip install --no-cache-dir your_package.whl


Remember your Python version

If you're using Python 2, it's pip install. If you're from the Python 3 world, remember to use pip3:

pip3 install your_package.whl   # For Python 3
pip install your_package.whl    # For Python 2


When things don't go as planned

Go to the Windows shop

Windows users can explore Christoph Gohlke's software shop to find ample .whl files. Make sure your Python version and the wheel file are compatible!

Bug fixing

Incorrect filenames or paths can bring up errors. So, before you start blaming pip, ensure your .whl filename and path are correct.

Search for answers

Refer to similar questions or guides if you're unable to solve the issue. Remember, every problem has a solution, you just need to find it!