wheel

0.46.3 · active · verified Sat Mar 28

wheel is the PyPA reference implementation of the Python wheel binary distribution format (PEP 427), providing a command-line tool for inspecting, unpacking, repacking, converting, and retagging .whl files. As of v0.46.0, it no longer ships the setuptools bdist_wheel command — that implementation now lives in setuptools ≥70.1. Current stable version is 0.46.3, released on a roughly quarterly cadence with occasional patch releases for CVEs and compatibility fixes.

Warnings

breaking v0.46.0 removed the bdist_wheel setuptools command implementation from wheel entirely. Projects with setuptools <70.1 that relied on wheel providing the bdist_wheel command will see 'error: invalid command bdist_wheel'. wheel.bdist_wheel is now only an alias pointing at setuptools.command.bdist_wheel.
Fix: Upgrade setuptools to ≥70.1 — it now ships bdist_wheel natively. Remove 'wheel' from build-system.requires unless you actually use the wheel CLI itself.
breaking wheel.metadata and internal submodules (wheel.cli, wheel._bdist_wheel, wheel.macosx_libfile removed in 0.46.0, temporarily restored in 0.46.1) are private. Importing them may raise ImportError across minor releases with no deprecation cycle.
Fix: Stop importing any wheel.* internal modules. Use the 'packaging' library for metadata/tag parsing, and invoke wheel functionality via subprocess or the CLI.
breaking wheel.macosx_libfile was removed in v0.46.0 and only temporarily restored in v0.46.1. Any code importing it is relying on an undocumented internal that will disappear again.
Fix: Do not import wheel.macosx_libfile. Depend on the platform tag detection built into setuptools or use macholib directly.
deprecated Importing wheel.bdist_wheel now emits a FutureWarning (was DeprecationWarning before v0.46.2). Custom bdist_wheel subclasses that inherit from wheel.bdist_wheel.bdist_wheel will break in a future release.
Fix: Change the base class to setuptools.command.bdist_wheel.bdist_wheel. See pypa/wheel#631.
gotcha Adding 'wheel' to build-system.requires in pyproject.toml is no longer necessary or recommended for setuptools-based projects. Listing it unnecessarily forces it to be installed even for sdist-only builds.
Fix: Remove 'wheel' from [build-system] requires = [...] unless your build script explicitly imports a wheel module at build time.
breaking v0.46.0 removed the vendored 'packaging' library and now requires it as an explicit runtime dependency. Environments where packaging is absent (e.g. minimal build containers) will get an ImportError when any wheel CLI command is invoked.
Fix: Ensure 'packaging' is installed in the environment. It is declared as a dependency so 'pip install wheel' installs it automatically, but manual/minimal installs must add it explicitly.
gotcha CVE-2026-24049 (fixed in v0.46.2): 'wheel unpack' could alter permissions of files outside the destination tree with a maliciously crafted wheel. Any version <0.46.2 unpacking untrusted wheels is vulnerable.
Fix: Upgrade to wheel>=0.46.2. Never unpack untrusted/third-party wheel files in production environments without sandboxing.

Install

pip install wheel pip
uv add wheel uv

Imports

wheel (CLI entry point)
```
import subprocess; subprocess.run(['wheel', 'unpack', 'some.whl'])
```
wheel exposes no stable public Python API. All functionality is through the 'wheel' CLI or 'python -m wheel'. Do not import internal modules like wheel.cli or wheel.metadata — both are private as of v0.46.0.
bdist_wheel (setuptools command)
```
from setuptools.command.bdist_wheel import bdist_wheel
```
wheel.bdist_wheel is now only an alias that emits a FutureWarning (changed from DeprecationWarning in v0.46.2). The real implementation lives in setuptools ≥70.1. Subclass from setuptools.command.bdist_wheel.bdist_wheel directly.
wheel.metadata (private module)
```
from packaging.metadata import Metadata
```
wheel.metadata was made a private module in v0.46.0 and emits a DeprecationWarning on import. Use the 'packaging' library for metadata operations instead.

Quickstart

wheel is a CLI-only tool. The four commands are: unpack (extract + verify hashes), pack (repack + regenerate RECORD), tags (retag for platform/interpreter/abi), and convert (egg→whl). All invoked via 'wheel <cmd>' or 'python -m wheel <cmd>'.

import subprocess
import sys

# Demonstrate the four main wheel CLI operations

# 1. Unpack a wheel (verifies RECORD hashes)
# subprocess.run(['wheel', 'unpack', 'someproject-1.0-py3-none-any.whl', '--dest', '/tmp/unpacked'], check=True)

# 2. Repack a previously unpacked wheel directory
# subprocess.run(['wheel', 'pack', '/tmp/unpacked/someproject-1.0', '--dest-dir', '/tmp/repacked'], check=True)

# 3. Retag a wheel (e.g. mark as universal py3)
# subprocess.run(['wheel', 'tags', '--python-tag', 'py3', 'someproject-1.0-py2-none-any.whl'], check=True)

# 4. Convert a legacy .egg to .whl
# subprocess.run(['wheel', 'convert', 'someproject-1.0-py3.egg'], check=True)

# Show installed wheel version
result = subprocess.run(
    [sys.executable, '-m', 'wheel', 'version'],
    capture_output=True, text=True
)
print(result.stdout.strip())

view raw JSON →