How to Install a Python Package with a .whl File?

by

Problem Formulation: Given a file yourPackage.whl that resides in the folder C:\your\folder\. How to install it on your Windows machine?

Background .whl Files

A .whl file (read: wheel file) is a zip archive that contains all the files necessary to run a Python application.

What is a wheel?

It’s a built-package format for Python, i.e., a zip archive with .whl suffix such as in yourPackage.whl. The purpose of a wheel is to contain all files for a PEP-compliant installation that approximately matches the on-disk format.

It allows you to migrate a Python application from one system to another in a simple and robust way.

Method 1: Powershell + pip + cd

This GIF shows you how you’d install a .whl package (e.g., downloaded from the Python Package index)—if unlike me, you’d downloaded the correct .whl file for your environment ;):

  • Open your Windows command line or Powershell.
  • cd into the folder where the yourPackage.whl file resides.
cd C:\your\folder\
  • Optional: Install pip on Windows. Chances are that it’s already installed—it comes with many Python distributions.
  • Run the following command:
pip install yourPackage.whl

Method 2: Powershell + pip without cd

  • Open your Windows command line or Powershell.
  • Optional: Install pip on Windows. Chances are that it’s already installed—it comes with many Python distributions.
  • Run the following command:
pip install C:\your\folder\yourPackage.whl

Method 3: Powershell + pip + wheel

  • Open the Powershell or command line in Windows
  • Upgrade pip to ensure that wheel is supported—which it is only for the newer versions of pip:
pip install --upgrade pip
  • Run the following command:
pip install --use-wheel --no-index --find-links=C:\your\folder\ yourPackage

Troubleshooting

If you experience problems with the installation, you may want to go over the following list with possible fixes, in this order:

  • Open the command line or Powershell as an administrator by right-clicking on the program symbol and select “Open as administrator”:
  • For Python 3, sometimes you’ll need to use the command pip3 instead of pip: 
pip3 install C:\your\folder\yourPackage.whl
  • Upgrade pip using the command in your Powershell or command line:
pip install --upgrade pip
  • If pip or pip3 still doesn’t work, try to run the following command to install the .whl package:
python -m pip install some-package.whl