Your Python Tests Passed. Your Published Wheel Is Missing Files.

In July 2026, MLX released version 0.32.0 of its Python package for macOS ARM64. The distribution wheel was missing important files, specifically all .pyi stub files that were present in the previous release. As a result, type checking functionality broke for downstream users since the tests did not detect the issue as they ran against the source code repository, not the wheel file.

This same issue was also observed in OpenSpace, where a tracked host_skills/ directory was unintentionally omitted during the distribution process, leading to broken integrations when users installed the package via pip. The root cause of both these bugs was a lack of artifact verification during the publishing process.

The standard Python tooling does not check if the files actually make it into the wheel or source distribution (sdist) that is uploaded to PyPI. This oversight can be easily exploited by build backends, MANIFEST.in glitches, and misconfigured package-data settings, leading to the same outcome of a missing file at runtime.

To address this problem, the author developed a tool called wheeltruth that checks the actual artifact served by PyPI, rather than the source repository. wheeltruth is a standard library-only Python command-line interface that verifies various aspects of the wheel distribution. When run against the built artifacts, wheeltruth performs the following checks:

1. RECORD completeness - It verifies that every file listed in the wheel's RECORD is present, has the correct SHA256 hash and size.

2. Entry point resolution - It ensures that each console_scripts and gui_scripts target points to an actual module inside the wheel.

3. Typing stub consistency - If a package includes .pyi stub files, wheeltruth checks that every module has a corresponding stub. An incomplete set of stubs (like in the MLX case) will be flagged.

4. METADATA consistency - It confirms that the package name and version match between the wheel file name and the wheel's own METADATA.

wheeltruth can also compare both the wheel and sdist distributions, highlighting files that were included in the sdist but missing from the wheel (like in the OpenSpace case), and vice versa. The tool supports both src/ layouts and ignores common test, docs, and other unrelated directories.

In addition to the standard checks, wheeltruth offers two additional modes for more paranoid checks:

1. It verifies that the packages declared in pyproject.toml or setup.cfg actually exist within the wheel.

2. It can perform a smoke test by installing the wheel into a throwaway virtual environment and attempting to import every top-level module.

The tool exits with a status code of 0 when no issues are found, and 1 when problems are detected, making it easy to integrate into continuous integration (CI) pipelines. An exit code of 0 indicates a clean build, while an exit code of 1 signals that problems were found and need to be addressed.

It's important to note the tool's limitations. As of version 0.1, wheeltruth only performs check operations and does not correct any configuration issues. The expected files are heuristics inferred from the sdist or project configuration, so exotic layouts may produce false positives. The smoke test requires a working virtual environment and takes a few seconds per wheel. Additionally, the stub check is a consistency check and cannot predict what was included in previous releases.