What the wheel auditor checks
A wheel is a ZIP archive whose filename carries distribution, version, optional build, Python, ABI, and platform fields. The auditor checks that filename against the single normalized .dist-info directory, core METADATA Name and Version, WHEEL Build and Tag fields, and required METADATA/WHEEL/RECORD members. It also validates ZIP boundaries, supported decompression, member CRC32 values, unsafe paths, duplicates, and bounded expansion before interpreting package metadata.
The format model follows the PyPA binary distribution format specification.
Why RECORD is checked separately from ZIP CRC
RECORD must list almost every wheel file with its exact uncompressed size and a URL-safe, unpadded secure hash. RECORD itself has empty hash and size fields; deprecated RECORD signature sidecars are special cases. The auditor recomputes SHA-256, SHA-384, and SHA-512 values with Web Crypto and rejects MD5, SHA-1, missing hashes, mismatches, missing members, duplicate rows, and unrecorded archive files. A matching ZIP CRC is transport evidence, not a substitute for RECORD.
How to read compatibility tags
Tags describe the interpreter, ABI, and operating-system or architecture policy intended by the builder. Compressed dot-separated fields expand to every combination. For example, py3-none-any declares generic Python 3, no ABI requirement, and no platform restriction; cp311-abi3-manylinux_2_17_x86_64 names CPython 3.11, the stable ABI, and a manylinux policy for x86-64 with a glibc floor. PyPA’s platform compatibility tag specification defines these fields.
Compatibility is still contextual. Installers compare the wheel’s tags with a ranked tag set computed from the actual interpreter and platform, while Requires-Python, dependencies, external shared libraries, CPU features, and package behavior can impose additional limits. Use python -m pip debug --verbose and an isolated target environment for the final decision.
Entry points and native code
entry_points.txt can request console wrappers, GUI wrappers, plug-ins, or application-specific hooks during or after installation. The auditor inventories their groups and import targets but never imports them. Common ELF, PE, Mach-O, .so, .pyd, .dll, and .dylib members are highlighted for review alongside a none-any declaration. Bundled binary data alone does not prove that runtime compatibility tags are wrong. This is an inventory, not malware analysis or dependency resolution.
Trust and installation boundary
Matching RECORD hashes prove consistency with declarations stored inside the same wheel; they do not establish publisher identity or package safety. Anyone able to replace a wheel can replace its RECORD too. The bounded model targets Wheel 1.0, warns on newer 1.x versions, reads core 1.x/2.x metadata, and does not validate every metadata field, dependency expression, license declaration, or installation-scheme behavior. This tool does not verify index hashes, attestations, Sigstore evidence, deprecated embedded signatures, source provenance, reproducibility, dependency safety, license compliance, native imports, or code behavior. Obtain the expected hash through a trusted channel, review provenance, and install only in an isolated environment with an approved installer.
Frequently asked questions
Does a clean audit mean the wheel is safe to install?
No. It means the supported structure and internal consistency checks found no errors. Python source, native code, build provenance, dependencies, and installation hooks still require trust and security review.
Why is RECORD’s own hash blank?
RECORD cannot contain a stable hash of itself. The wheel specification therefore requires its own row with empty hash and size fields.
Why are RECORD.jws and RECORD.p7s not treated as proof?
The current wheel specification deprecates those embedded signature sidecars. More importantly, authenticity needs an independently trusted identity or expected digest, not merely evidence carried inside the same archive.
Can this tell whether the wheel works on my machine?
It explains the declared tags and cross-checks them internally. Use your actual installer’s supported-tag calculation and a disposable environment to decide and test compatibility.