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 passing test run in your project checkout does not prove that a built wheel contains the modules and runtime resources your package needs. The reliable check is to inspect the wheel, install it outside the checkout, and test that installed copy. First identify whether the missing file was lost during package discovery, sdist selection, or wheel assembly; then configure the build backend that your project actually uses.
Why can tests pass when the wheel is missing files?
Tests run from a checkout can see files sitting in the repository, even when those files were not selected for the built distribution. The result may be an installable package that fails when an import or runtime resource lookup reaches a missing file. The build project’s troubleshooting guide describes this symptom as a package that installs but is missing source files, data files, or modules.
A source distribution (sdist) and a wheel are separate artifacts with separate inclusion steps. An sdist is source material that can be used to build an installation artifact; a wheel is the built artifact installed by a package installer. A file can be in the repository or sdist and still be absent from the wheel. The packaging flow explains the distinction, while setuptools documents that MANIFEST.in controls the sdist file list—not, by itself, the wheel’s contents.
Find which files and artifact are affected
Start with an inventory of what the installed package needs. Separate importable Python modules and subpackages from non-Python resources such as templates, JSON, data, and schemas, and from files intended to live outside the importable package. Mark development-only files so you do not spend time trying to ship them unnecessarily.
#1 Best Overall
- Module or subpackage missing: check package discovery and, for standalone modules, whether the backend has been told to include them.
- Resource inside a package missing: check the backend’s package-data configuration and the resource’s path and glob.
- File absent from the sdist: inspect the sdist’s file-selection configuration, including
MANIFEST.inwhen using setuptools. - File present in the sdist but absent from the wheel: check wheel inclusion settings; sdist inclusion alone is not proof of wheel inclusion.
The wheel specification describes a .data directory structure for files destined for installation locations outside the usual site-packages path. That mapping is for files with those destinations; it is not a general place to put package resources. See the wheel specification.
Identify the build backend before changing settings
Read the [build-system] section of pyproject.toml to identify the backend. Configuration for setuptools is not a universal fix: Hatchling, Flit, and other backends have their own package-discovery and file-inclusion rules. Use the documentation for the backend named by the project, as the PyPA packaging tutorial and build troubleshooting guide explain.
For any backend, compare its discovery configuration with the actual project layout. A src/ tree can be missed if discovery is aimed at the wrong location; an unconfigured package or standalone .py module can also be left out. The PyPA setuptools guide covers package discovery and py_modules for setuptools projects.
Configure setuptools resources for the wheel
For a setuptools project using pyproject.toml, [tool.setuptools.package-data] explicitly maps package names to resource-file globs. For example, the build troubleshooting guidance uses this form:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
[tool.setuptools.package-data]
mypackage = ["data/*.json", "templates/*.html"]Replace mypackage and the patterns with the real import package and files your installed code reads. These patterns use forward slashes, including on Windows. A pattern does not match dotfiles unless it explicitly accounts for them. Setuptools says package_data does not require the matched files to be listed in MANIFEST.in or tracked by a revision-control plugin. See setuptools’ data-files documentation.
Understand what include_package_data does
Do not read include_package_data as “include every file in the repository.” Setuptools’ current documentation says its default is true for projects configured through pyproject.toml (a behavior added in setuptools 61.0.0); for setup.cfg and setup.py, the compatibility default remains false. Its normal scope is non-Python files inside a package directory that meet the documented inclusion conditions, not arbitrary project files. If a project mixes configuration styles, verify which setting is active. The details and conditions are in the data-files documentation and setuptools’ file-control guide.
Use MANIFEST.in for the sdist, not as a wheel guarantee
With setuptools, MANIFEST.in adjusts which files go into the sdist. Those source files may be available during a later build, and wheel inclusion can be configured separately, but adding a file to the manifest alone does not establish that it is in the wheel. Setuptools’ file-control guide also notes that include_package_data=True includes files inside the package directory by default, subject to the documented conditions. Check both artifacts when you distribute both.
Build and test the artifacts you will release
Use the build frontend to create the actual artifact, then inspect the archive rather than relying on a successful build message. The PyPA packaging flow describes python -m build --wheel and python -m build --sdist; running python -m build without either flag builds both by default.
- Build what you distribute. Run
python -m build --wheelfor a wheel. If you also publish an sdist, build it separately withpython -m build --sdist. - Inspect each archive. Open the
.whland confirm the required module paths and resource files are present. For an sdist, the build guide demonstrates listing its contents withtar -tzf dist/mypackage-1.0.0.tar.gz; substitute the actual archive name. - Install the wheel outside the checkout. Use a clean virtual environment or another environment that is not running from the project directory. This prevents the working tree from supplying a missing module or resource.
- Exercise installed behavior. Import the package and run checks that load its real runtime resources. Test the installed distribution, not only code executed from the repository.
twine check dist/*, shown in the PyPA setuptools guide, is a complementary distribution check. It is not evidence that every runtime file is present in the wheel.
If corrected settings do not change the archive
Setuptools documents build directories, dist, and *.egg-info as places that can contain build artifacts or cached files. In particular, its data-files documentation warns that an sdist can draw from package_name.egg-info/SOURCES.txt as a cache; after changing package_data, remove that stale file and rebuild if the archive still contradicts the configuration. The file-control guide covers build artifacts, and the data-files guide describes the SOURCES.txt caveat.
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.
