wheel

wheel is the reference implementation for working with the Python wheel (.whl) binary distribution format defined in PEP 427. It provides the wheel command-line tool for packing, unpacking, repacking, retagging, and inspecting wheel archives, plus a small importable API (wheel.wheelfile.WheelFile) that other packaging tools build on for RECORD-hash-verified, zip-based read and write access to wheels.

Originally the package also carried the bdist_wheel distutils command used by build backends to produce wheels, but as of setuptools 70.1 that implementation lives in setuptools itself; wheel’s bdist_wheel module is now only a deprecation shim that re-exports it. Today the project’s active surface is its CLI: converting legacy .egg archives to .whl, unpacking or repacking wheel contents for inspection or patching, and adding, removing, or replacing platform-compatibility tags without a full rebuild.

What You Get

• A wheel CLI with pack, unpack, convert, tags, and info subcommands for working with .whl files directly.
• A WheelFile class (wheel.wheelfile) that subclasses zipfile.ZipFile and verifies every read file’s SHA-256 hash against the wheel’s RECORD entry.
• Egg-to-wheel conversion for migrating legacy .egg distributions and old Windows installer executables into the modern wheel format.
• In-place tag rewriting (wheel tags) to add, remove, or replace Python/ABI/platform compatibility tags on an already-built wheel without recompiling.
• PEP 566 core-metadata parsing and writing helpers (wheel.metadata) shared with other packaging tools.

Common Use Cases

• Inspecting a .whl file’s contents and metadata before publishing it to PyPI.
• Repairing or relabeling a built wheel’s platform tags for a different target environment.
• Converting an old .egg package into a wheel to modernize a legacy build pipeline.
• Unpacking a wheel to a directory for manual inspection or patching of a third-party package.

Under The Hood

Architecture The CLI entry point (wheel/_commands/__init__.py) wires an argparse subparser tree (unpack, pack, convert, tags, info, version) where each subcommand lazily imports its implementation module from _commands/ to keep startup fast; those implementation modules each own one wheel-manipulation operation and route all wheel reads and writes through the core wheelfile.py module, which subclasses zipfile.ZipFile as WheelFile to add PEP-427-compliant per-file RECORD hash verification. Metadata parsing lives separately in metadata.py/_metadata.py, and macosx_libfile.py is an isolated low-level Mach-O binary parser used only by the tag-rewriting path. The legacy bdist_wheel.py module is a thin deprecation shim re-exporting the bdist_wheel command from setuptools rather than owning build-backend integration itself. This is a clean, single-responsibility command layout — swapping the core WheelFile abstraction would ripple through every command module, since pack, unpack, convert, and info all depend on it exclusively.

Tech Stack Pure Python 3.9+ with a single runtime dependency (packaging>=24.0); built with the flit_core backend rather than setuptools, reflecting its place in the modern packaging-tooling ecosystem. The project is distributed both as an importable library (wheel.wheelfile.WheelFile, wheel.metadata) and as a console-script CLI registered via [project.scripts], and publishes itself to PyPI through a dedicated GitHub Actions workflow.

Code Quality Tests mirror the source layout (tests/test_wheelfile.py, tests/commands/test_pack.py, etc.) using pytest fixtures and parametrization, with --strict-markers, --strict-config, and filterwarnings = ["error", ...] enforcing zero tolerance for warnings in CI, plus xfail_strict. Code is consistently type-annotated (from __future__ import annotations throughout) and linted with an extensive ruff rule set including flake8-annotations, bugbear, and pyupgrade. Errors are surfaced explicitly through a dedicated WheelError exception rather than swallowed, and a tox matrix runs the suite across Python 3.9 through 3.14 plus PyPy in CI.

What Makes It Unique wheel isn’t chasing novelty — it’s the canonical, spec-compliant reference implementation of the wheel format itself, so its distinguishing technical choice is faithfully enforcing PEP 427 semantics (per-file SHA-256 verification against RECORD, monkey-patched CRC checking during extraction) rather than introducing a new abstraction. Its value is foundational rather than innovative: nearly every Python packaging tool that touches wheels relies on its correctness.