Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Python wheel

From ReverseEngineering.wiki
Format
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 purelib or platlib (both usually site-packages).
  • {distribution}-{version}.dist-info/ holds METADATA (core metadata, the same format as PKG-INFO in an sdist), WHEEL, RECORD, optional entry_points.txt, licenses/ and other reserved subdirectories. Console and GUI script wrappers are generated from entry_points.txt (group console_scripts; Unverified: gui_scripts is 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 in scripts/ that begin with exactly #!python (or #!pythonw for 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

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