Introduction

To install a Python package from a .whl file, run pip install path/to/package.whl. Wheel files are pre-built binary distributions that install faster than source distributions because they skip the compilation step. They are the standard format for distributing Python packages and have replaced eggs since PEP 427.

What Is a .whl File?

A .whl file is a ZIP archive with a specific naming convention that tells pip which Python version, platform, and ABI it targets. The format follows this pattern:

{package}-{version}(-{build})?-{python}-{abi}-{platform}.whl

For example:

numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl

Breaking this down:

A wheel with py3-none-any in its name is a pure Python package that works on any platform and any Python 3 version.

Basic Installation

Step 1: Verify Your pip Version

Pip 1.4+ supports wheel files natively. Check and upgrade if needed:

pip --version
pip install --upgrade pip

Step 2: Install the Wheel File

Navigate to the directory containing the .whl file and run:

pip install numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl

Or provide the full path without changing directories:

pip install /Users/yourname/Downloads/numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl

Step 3: Verify the Installation

pip show numpy
python -c "import numpy; print(numpy.__version__)"

Installing into a Virtual Environment (Recommended)

Always install packages into a virtual environment to avoid conflicts with system Python:

1# Create a virtual environment
2python -m venv myproject_env
3
4# Activate it
5# macOS/Linux:
6source myproject_env/bin/activate
7# Windows:
8myproject_env\Scripts\activate
9
10# Install the wheel
11pip install /path/to/package.whl
12
13# Verify
14pip list

Where to Download .whl Files

PyPI (Official Source)

Download wheels directly from PyPI when you need offline installation or a specific version:

1# Download without installing
2pip download numpy==1.26.4 -d ./wheels/
3
4# Download for a specific platform (useful for CI)
5pip download numpy==1.26.4 \
6  --platform manylinux2014_x86_64 \
7  --python-version 312 \
8  --only-binary=:all: \
9  -d ./wheels/

Unofficial Binaries (Windows)

For Windows packages that are hard to compile (like GDAL, rasterio, or Shapely), Christoph Gohlke's archive at https://www.lfd.uci.edu/~gohlke/pythonlibs/ historically provided pre-built wheels. This site is now archived, but many of these packages now publish official wheels on PyPI.

Building Your Own Wheel

You can build a wheel from a source distribution:

1# Build a wheel from a source package
2pip wheel /path/to/source/package/ -w ./wheels/
3
4# Build from a requirements file
5pip wheel -r requirements.txt -w ./wheels/

Installing Multiple Wheels and Dependencies

Install Multiple Wheels from a Directory

1# Install all wheels in a directory
2pip install ./wheels/*.whl
3
4# Install from a directory with no internet (offline mode)
5pip install --no-index --find-links=./wheels/ numpy pandas scipy

Handle Dependencies Automatically

Pip resolves dependencies from PyPI by default. If a wheel depends on other packages, pip downloads and installs them automatically:

pip install mypackage-1.0-py3-none-any.whl
# pip will fetch dependencies from PyPI

For fully offline installation, download all dependencies first:

1# Download the package and all its dependencies as wheels
2pip download numpy -d ./wheels/
3
4# Install everything offline
5pip install --no-index --find-links=./wheels/ numpy

Wheel vs Source Distribution vs Egg

Wheels are preferred because they do not execute arbitrary code during installation. Source distributions run setup.py, which can execute anything.

Compatibility and Platform Matching

Check Your Python and Platform Tags

To install a wheel, your environment must match the wheel's tags. Check what your pip supports:

pip debug --verbose

This shows supported tags like:

1Compatible tags: 37
2  cp312-cp312-macosx_14_0_arm64
3  cp312-cp312-macosx_14_0_universal2
4  cp312-abi3-macosx_14_0_arm64
5  ...
6  py3-none-any

Force Install an Incompatible Wheel

If you are certain a wheel is compatible despite tag mismatches (for example, a manylinux2014 wheel on a newer Linux):

pip install package.whl --force-reinstall

For truly incompatible wheels, rename the file to match your platform (not recommended, and may cause runtime crashes).

Common Pitfalls

• "is not a supported wheel on this platform": The wheel's Python version, ABI, or platform tag does not match your environment. Run pip debug --verbose to see which tags your pip supports. You likely downloaded a wheel for the wrong Python version or OS.
• "No matching distribution found": When using pip install with --find-links, pip might skip the local .whl file if a newer version exists on PyPI. Add --no-index to force pip to use only local files.
• Using sudo pip install: This installs packages into the system Python, which can break OS-level tools. Use virtual environments instead. If you must install system-wide, use pip install --user package.whl.
• Pip version too old: Pip versions before 1.4 do not support wheel files. Pip versions before 19.0 do not support manylinux2010 wheels. Always upgrade pip first: pip install --upgrade pip.
• Missing build dependencies for source fallback: If a wheel is not available and pip falls back to building from source, you need compilers (gcc, MSVC) and development headers installed. The wheel format exists specifically to avoid this problem.
• Confusing pip install wheel with installing a .whl file: The package named wheel is a build tool. Installing it with pip install wheel does not install any .whl file you have downloaded.

Summary

• Install a wheel file with pip install path/to/package.whl. No additional tools required beyond pip 1.4+.
• Wheels are pre-built binary packages that skip compilation, making installation faster and safer than source distributions.
• Always use a virtual environment to avoid polluting your system Python.
• Download wheels for offline use with pip download package -d ./wheels/, then install with pip install --no-index --find-links=./wheels/ package.
• Check platform compatibility with pip debug --verbose if you get "not a supported wheel on this platform" errors.
• Prefer wheels over source distributions for security: wheels cannot execute arbitrary code during installation.