Check Wheel Contents

0.6.3 · active · verified Thu Apr 16

check-wheel-contents is a command-line tool designed to validate the structure and contents of Python wheel (.whl) files, helping developers avoid common packaging mistakes before publishing. It analyzes wheels for issues like incorrect file placement, duplicate files, or inclusion of unwanted artifacts (`.pyc` files, `tests/` directories). Maintained actively, it currently supports Python 3.10 and newer.

Common errors

```
W001 — Wheel contains .pyc/.pyo files
```
cause The wheel includes compiled Python bytecode (.pyc or .pyo) files.

fix Exclude `*.pyc` and `*.pyo` files from your wheel build process, typically by adding `global-exclude *.py[co]` to your `MANIFEST.in` (for setuptools projects) or configuring your build backend accordingly.
```
W002 — Wheel contains duplicate files
```
cause Two or more files within the wheel have identical contents (excluding very common empty files or boilerplate headers). This often indicates a build artifact or a mistaken copy.

fix Delete the `build/` directory and rebuild the wheel to resolve stale files. Review your packaging configuration to ensure no files are being copied instead of moved or renamed, or included twice from different sources.
```
W009 — Wheel contains multiple toplevel library entries
```
cause The purelib or platlib section of the wheel contains more than one top-level directory or module (e.g., your package plus a 'tests/' directory).

fix Adjust your build configuration (e.g., `setuptools.find_packages()` exclusions, `package_dir` settings) to ensure only the intended main package(s) are installed at the top level of `site-packages`.
```
W102 — Wheel library contains files not in package tree
```
cause This check, enabled when `--package` or `--src-dir` is set, indicates that the wheel contains files that do not exist in the specified local package source tree.

fix Verify that all files included in the wheel are genuinely part of your project's source. This might involve cleaning your build directory (`rm -rf build dist/`) and rebuilding, or correcting your `MANIFEST.in` or build configuration to accurately reflect your source layout.

Warnings

gotcha Including '__init__.py' at the root of your wheel's 'purelib' or 'platlib' section is a common packaging error. `__init__.py` files belong inside package directories, not at the root of the installation.
Fix: Ensure your project uses a 'src/' layout (e.g., `package_dir={'': 'src'}` in `setup.py` or equivalent in `pyproject.toml`) and that no `__init__.py` exists directly in `src/` or the project root if it's not part of a package.
gotcha Including compiled Python bytecode files (`.pyc` or `.pyo`) in your wheel is incorrect. Pip generates these files automatically during installation, and including them makes your wheel unnecessarily larger and potentially platform-specific.
Fix: Add `global-exclude *.py[co]` to your `MANIFEST.in` file (if using `setuptools`) to prevent these files from being included, ensuring it's placed correctly if you're also using `graft` or `recursive-include`.
gotcha Failing to delete your `build/` directory before rebuilding a wheel (especially with setuptools) can lead to stale or incorrect files being included, causing checks to fail or new issues to appear.
Fix: Always clean your build environment by deleting the `build/` and `dist/` directories (e.g., `rm -rf build dist/`) before performing a new wheel build.
gotcha A wheel containing multiple top-level library entries (modules or packages not starting with an underscore, excluding `.pth` files) is generally a sign of incorrect packaging, as most projects intend to distribute a single top-level package.
Fix: Review your `setup.py` or `pyproject.toml` configuration to ensure only your main package(s) are included. Use `exclude` arguments in `find_packages()` or explicitly list packages/modules, ensuring that test directories or other artifacts are not inadvertently included at the top level.

Install

pip install check-wheel-contents Install latest version

Quickstart

After building your Python wheel, typically using `python -m build --wheel` which places it in a `dist/` directory, run `check-wheel-contents` on the generated `.whl` file or the directory containing it. The tool will print 'OK' if all checks pass, or detailed error messages for any failures.

# Build your wheel first, typically into a 'dist/' directory
# python -m build --wheel

# Run check-wheel-contents on a single wheel file
check-wheel-contents dist/my_package-0.1.0-py3-none-any.whl

# Or check all wheels in a directory
check-wheel-contents dist/

view raw JSON →