The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →A successful test run from your checkout does not prove that your published wheel contains the modules and resources your package needs. Tests may import code and read files directly from the repository, while the build backend selects a different set of files for the wheel. Check the backend and its file-selection settings, inspect the actual wheel, then install and test that wheel outside the checkout.
Why can tests pass while the installed package is missing files?
The checkout contains files that may not be selected for a distribution. As the build project’s troubleshooting guide describes the symptom, “After building, the package installs but is missing source files, data files, or modules.” The omission can happen during package discovery, when files are selected for the source distribution (sdist), or when the wheel is assembled.
A wheel is a built installation artifact; an sdist is source used to build an installation artifact. They have separate inclusion checks. A file can be present in the repository and sdist but absent from the wheel. MANIFEST.in controls the sdist file list; by itself, it is not a guarantee that a file will be included in a wheel. The PyPA packaging flow and its setuptools distribution guide explain the distinction.
First identify what is missing and which artifact needs it
Make an inventory of the absent files and classify each one before changing configuration. Is it an importable module, a resource loaded at runtime, or a file intended for a location outside the importable package? Keep development-only files separate from files needed by installed users.
#1 Best Overall
- Python modules or subpackages: Check that package discovery matches the project layout and that standalone modules are declared where required.
- Package resources: Identify templates, JSON, schemas, or other files the installed code opens at runtime.
- External data files: Determine whether they belong in the wheel and where the installer should place them. The wheel specification describes the
.datadirectory structure used for files destined for locations outside the normalsite-packagespath; it is not a general place for all package resources.
Decide whether the file must be in the wheel, the sdist, or both. If you publish both, inspect both independently.
Find the backend and check package discovery
Open pyproject.toml and check its [build-system] section to identify the build backend. Inclusion settings are backend-specific: a setuptools configuration is not automatically applicable to Hatchling, Flit, or another backend. Follow the documentation for the backend actually named in the project. The PyPA packaging tutorial and build troubleshooting guide cover common discovery and layout problems.
For setuptools, check that discovery points to the real package directory, especially when using a src/ layout. Also verify that standalone .py modules are configured when needed. The setuptools distribution guide describes package configuration, including packages and py_modules.
For setuptools, configure resources for the wheel
For resources inside a package, setuptools provides package_data; in pyproject.toml, use [tool.setuptools.package-data]. For example:
[tool.setuptools.package-data]
mypackage = ["data/*.json", "templates/*.html"]This explicitly names resource patterns for the package. Setuptools documents that package_data does not require the same patterns to be added to MANIFEST.in or tracked by a revision-control plugin. See Setuptools Data Files Support.
Do not treat include_package_data as “include every file in the repository.” Its behavior depends on configuration style: the current setuptools documentation says it defaults to true for projects configured through pyproject.toml (a default added in setuptools 61.0.0), while setup.cfg and setup.py retain a false default for compatibility. Its normal scope is non-Python files inside a package directory that meet the documented inclusion conditions. If a project mixes configuration styles, verify which setting is active. These details are documented in Setuptools Data Files Support and Controlling files in the distribution.
Setuptools resource patterns use forward slashes, including on Windows. Dotfiles are not matched unless the pattern explicitly accounts for them. MANIFEST.in remains relevant when controlling the sdist file list, but its presence alone does not configure wheel contents.
Inspect and test the built artifacts
Build the artifacts you intend to publish, then inspect their contents. The PyPA packaging flow documents python -m build --wheel and python -m build --sdist; without either flag, the build command builds both.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Build the wheel: Run
python -m build --wheelfrom the project root. - Inspect the archive: Open the resulting
.whlfile with an archive viewer or list its contents programmatically. Confirm that every required module and runtime resource is present. - Install outside the checkout: Create a clean virtual environment in a directory outside the project, install the built wheel, and run import and resource-loading checks there. This helps prevent the working tree from satisfying imports or file reads that would fail for users.
- Check the sdist separately if you publish one: Build it with
python -m build --sdistand list its contents. The build guide demonstratestar -tzf dist/mypackage-1.0.0.tar.gz; replace the example archive name with your build’s filename. See build troubleshooting.
twine check dist/*, shown in the PyPA setuptools guide, is a complementary distribution validation step. It checks metadata and descriptions; it does not establish that the wheel contains every runtime file.
If the corrected configuration still appears to have no effect
Rebuild from a clean state when the archive does not reflect a file-selection change. Setuptools identifies build directories, dist, and *.egg-info as locations for artifacts and cached files that can become stale in edge cases. Its data-files documentation specifically warns that an sdist may use package_name.egg-info/SOURCES.txt as a cache and advises removing it after updating package_data before rebuilding. See Controlling files in the distribution and Setuptools Data Files Support.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
