Python Wheel Distribution — Core Concepts

Why this topic matters

Before wheels (PEP 427, introduced in 2012), installing Python packages meant running arbitrary setup.py code during installation. This was slow, insecure, and frequently failed when build tools weren’t available. Wheels replaced this with a simple archive format that pip extracts without executing any code — making installation faster, safer, and more reproducible.

How it works

A wheel file is a ZIP archive with a .whl extension. The filename follows a strict convention:

package_name-version-python_tag-abi_tag-platform_tag.whl

Examples:

requests-2.31.0-py3-none-any.whl
numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.whl
cryptography-42.0.0-cp312-cp312-macosx_14_0_arm64.whl

Decoding the filename

Tag	Meaning	Example
Python tag	Python implementation + version	py3 (any Python 3), cp312 (CPython 3.12)
ABI tag	Application Binary Interface	none (pure Python), cp312 (CPython 3.12 ABI)
Platform tag	Operating system + architecture	any, manylinux_2_17_x86_64, win_amd64

A pure Python package uses py3-none-any — it works on any Python 3 implementation, any ABI, any platform. Packages with C extensions need platform-specific wheels.

Key concepts

Inside a wheel

Unzipping a wheel reveals a simple structure:

my_package/
├── __init__.py
├── core.py
└── _fast.cpython-312-x86_64-linux-gnu.so   # Compiled extension
my_package-1.0.0.dist-info/
├── METADATA         # Package name, version, dependencies
├── WHEEL            # Wheel format metadata
├── RECORD           # Checksums of all files
├── entry_points.txt # CLI commands and plugins
└── LICENSE

The .dist-info directory contains everything pip needs to track the installation, handle uninstallation, and resolve dependencies.

Why wheels are faster

Installation speed comparison for a package like pandas:

Method	Steps	Typical time
Source (sdist)	Download → extract → compile C → install	60-120 seconds
Wheel	Download → extract ZIP → done	2-5 seconds

For pure Python packages the difference is smaller but still noticeable. For packages with C extensions (NumPy, pandas, cryptography, Pillow), wheels eliminate the need for a C compiler entirely.

Manylinux: solving Linux compatibility

Linux distributions vary in their system libraries. A wheel built on Ubuntu 22.04 might not work on CentOS 7. The manylinux standard defines a minimal set of system libraries that a wheel can depend on:

• manylinux2014: Compatible with glibc 2.17+ (CentOS 7+)
• manylinux_2_28: Compatible with glibc 2.28+ (Ubuntu 20.04+)

Wheels built inside a manylinux Docker container are guaranteed to work across Linux distributions that meet the glibc requirement. The auditwheel tool verifies and repairs wheels for manylinux compliance.

Building your own wheels

For your project:

pip install build
python -m build --wheel

For installing all your dependencies as wheels (useful for air-gapped deployments):

pip wheel -r requirements.txt -w wheelhouse/
# Later, install from the cache
pip install --no-index --find-links=wheelhouse/ -r requirements.txt

Wheel caching

Pip caches downloaded and built wheels automatically:

# See cache location
pip cache dir

# List cached wheels
pip cache list

# Clear cache
pip cache purge

Subsequent installs of the same package version use the cached wheel, avoiding downloads.

Common misconception

“Wheels and eggs are the same thing.” Eggs were an older distribution format from setuptools (.egg files). Wheels replaced them as the standard. Key differences: wheels are simpler (just ZIP files, no code execution during install), have a standardized filename convention for platform compatibility, and are an official Python packaging standard (PEP 427). Eggs are effectively deprecated.

One thing to remember

Wheels are the modern standard for distributing Python packages. They install instantly, don’t execute arbitrary code, and encode platform compatibility in their filename — making pip installations fast, safe, and predictable.