Format:Python wheel
| Magic | PK\x03\x04 (ZIP); name ends in .whl |
|---|---|
| Extensions | .whl |
| On this wiki | Facts · Code · Notes · Topics |
Python's built distribution (.whl): a ZIP named name-version[-build]-python-abi-platform.whl holding the files to unpack into site-packages, a name-version.dist-info directory (METADATA, WHEEL, RECORD with sha256 hashes, entry_points.txt) and an optional .data directory; installing it runs no package code.
A wheel is the standard binary (built) distribution of Python packages, defined by the PyPA binary distribution format specification (PEP 427 and its successors). It is an ordinary Format:ZIP archive; file names inside are UTF-8. Unlike an sdist (Format:Python sdist), a wheel carries no setup.py or setup.cfg and installing it only unpacks files, so reading its file list tells you exactly what lands on disk.
File name
{distribution}-{version}(-{build})?-{python}-{abi}-{platform}.whl, for example distribution-1.0-py32-none-any.whl. The distribution and version fields may not contain - (runs of -_. in the name become _). The optional build tag must start with a digit. The last three fields are compatibility tags and may be compressed sets joined with . (for example py2.py3). pypa/wheel matches the name with the regex in wheelfile.py (WHEEL_INFO_RE); pypa/packaging parse_wheel_filename accepts 4 or 5 dashes in the stem and rejects a project name containing __.
Contents
- The archive root holds the files that go into
pureliborplatlib(both usually site-packages). {distribution}-{version}.dist-info/holdsMETADATA(core metadata, the same format as PKG-INFO in an sdist),WHEEL,RECORD, optionalentry_points.txt,licenses/and other reserved subdirectories. Console and GUI script wrappers are generated fromentry_points.txt(groupconsole_scripts; Unverified:gui_scriptsis the GUI counterpart) by the installer, they are not stored in the wheel.{distribution}-{version}.data/has one subdirectory per install-scheme key:purelib,platlib,headers,scripts,data. Files inscripts/that begin with exactly#!python(or#!pythonwfor GUI) are rewritten to the target interpreter at install time.
WHEEL file
Key: value text lines:
Wheel-Version: 1.0
Generator: bdist_wheel 1.0
Root-Is-Purelib: true
Tag: py2-none-any
Tag: py3-none-any
Build: 1
Root-Is-Purelib: true means the archive root is unpacked into purelib, otherwise into platlib (so false marks a platform-specific wheel with compiled extension modules at the root). An installer warns on a greater minor Wheel-Version and must fail on a greater major one. There is one Tag line per expanded tag combination, which is how to read what the filename's compressed tags mean.
RECORD
A CSV file (path,algorithm=urlsafe-base64-digest-without-padding,size) listing every file with its hash; RECORD itself has empty hash and size. The algorithm must be sha256 or stronger (md5 and sha1 are refused). RECORD.jws and RECORD.p7s are deprecated signature files and are not listed in RECORD. Installers check every file's hash against RECORD and fail if a file is missing from it. For analysis, the hashes let you compare a wheel's files with the sdist or with the installed tree without extracting twice.
Installing
Unpack the root into purelib or platlib, move each .data/<key> subtree to its sysconfig path, rewrite #!python scripts, update RECORD with the installed paths and compile .py to .pyc. Native code in a wheel (.so, .pyd) therefore runs only when something imports it, not at install time. Code can still run at import time of any module and through .pth files placed in site-packages (Unverified: .pth lines starting with import are executed by the site module at interpreter start; read CPython Lib/site.py to confirm).
Related
- Format:Python sdist, Technique:Install-time code execution in package archives, legacy eggs: Unverified: a
.eggis a ZIP (or directory) with anEGG-INFO/directory holding PKG-INFO, and was replaced by wheels.
Sources
See the facts attached to this page: pypa/wheel src/wheel/wheelfile.py, pypa/packaging src/packaging/utils.py, and the PyPA specification binary-distribution-format.rst and entry-points.rst. The entry_points.txt INI details (sections are groups, name = module:attr [extras] lines) were read in the entry points specification only to the extent of its data model; the exact section syntax of [extras] was not checked.
Code & repositories
- https://github.com/pypa/wheel @
4ae6d07d38611cb0619864621c06fc032622eaef· license: MIT
Reference implementation of the wheel archive reader/writer (wheelfile.py, RECORD handling).
Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-05 - https://github.com/pypa/packaging @
ef837aad3127167671eb37b9f6bd8a94ec7ce26e· license: Apache-2.0 OR BSD-2-Clause (declared by the contributor; GitHub's detector did not recognize LICENSE)
PyPA packaging library: wheel and sdist file name parsing in utils.py.
Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-13