{"id":7075,"library":"check-wheel-contents","title":"Check Wheel Contents","description":"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.","status":"active","version":"0.6.3","language":"en","source_language":"en","source_url":"https://github.com/jwodder/check-wheel-contents","tags":["packaging","wheel","linting","build","ci"],"install":[{"cmd":"pip install check-wheel-contents","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[],"quickstart":{"code":"# Build your wheel first, typically into a 'dist/' directory\n# python -m build --wheel\n\n# Run check-wheel-contents on a single wheel file\ncheck-wheel-contents dist/my_package-0.1.0-py3-none-any.whl\n\n# Or check all wheels in a directory\ncheck-wheel-contents dist/","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The wheel includes compiled Python bytecode (.pyc or .pyo) files.","error":"W001 — Wheel contains .pyc/.pyo files"},{"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.","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.","error":"W002 — Wheel contains duplicate files"},{"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`.","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).","error":"W009 — Wheel contains multiple toplevel library entries"},{"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.","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.","error":"W102 — Wheel library contains files not in package tree"}]}