To put runtime data files in a Python wheel, first check the build backend in pyproject.toml. For setuptools, the most direct option is [tool.setuptools.package-data], with globs relative to the importable package. For Poetry, set the included files’ format to include wheel. The syntax differs by backend, and an entry in MANIFEST.in alone does not guarantee that a file will be in a setuptools wheel.
Start by identifying the build backend
The [build-system] table names the backend that builds the project. The settings under [tool.*] are interpreted by the corresponding tool, so setuptools configuration is not interchangeable with Poetry configuration. Check the build-backend value before adding file-selection rules. See the Python Packaging User Guide and your backend’s documentation: setuptools pyproject configuration or Poetry’s pyproject reference.
For setuptools, select runtime files with package-data
Use [tool.setuptools.package-data] when you want a clear, package-specific rule for files that must be installed with the code. The table keys are importable package names, which can differ from the project’s distribution name on PyPI. Patterns are relative to the package directory.
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[project]
name = "example"
version = "0.1.0"
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
mypkg = ["data/*.json"]For this src layout, the rule matches files such as src/mypkg/data/schema.json, assuming discovery includes mypkg. A pattern such as mypkg = ["*.txt", "*.rst"] selects files directly inside the package; include nested paths in the pattern when the files are in subdirectories. Use forward slashes in patterns, including on Windows. Dotfiles are not matched unless the pattern explicitly begins with a dot, for example ".*". The setuptools data-files guide documents package-data selection.
#1 Best Overall
Make sure the package itself is discovered
A correct data pattern cannot add files to a package that the backend has not selected. For a src layout, set the discovery root appropriately, as in where = ["src"], and verify that the target package is included. Namespace packages and packages without __init__.py may need deliberate discovery configuration if you configure packages manually; setuptools can treat directories without that file as packages, but manual settings must account for them.
When include-package-data is a better fit
Setuptools’ include-package-data option can be useful when the same file-selection process should feed both source distributions and wheels. It includes package files that have been selected through mechanisms such as MANIFEST.in or a version-control plugin. It does not mean every file at the project root will be placed in the wheel: with this option enabled, setuptools’ default wheel behavior is limited to files inside package directories.
For projects configured through pyproject.toml, setuptools defaults include-package-data to true beginning with setuptools 61.0.0. Projects configured through setup.cfg or setup.py retain a false default for backward compatibility. Make the option explicit if you need the configuration to be immediately clear to maintainers, and check the project’s selection rules rather than assuming the default includes a particular file.
Understand what MANIFEST.in does—and does not do
MANIFEST.in controls which files setuptools adds to or removes from the source distribution (sdist). Its directives include include, exclude, recursive-include, and graft, along with removal counterparts. Setuptools commonly builds a wheel from the sdist, but the sdist can contain development or build files that are not runtime files in the wheel.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Do not rely on a MANIFEST.in entry by itself to put an arbitrary project-level file in a wheel. For runtime resources, keep files inside the importable package and select them with package-data, or confirm that the backend’s package-data inclusion behavior covers them. A project-level file needed only by source builds can remain an sdist-only file. See the setuptools guide to including data files.
If the project uses Poetry
Poetry uses its own packages, include, and exclude settings. Use packages when automatic discovery misses a Python package or module; use include for file patterns. Include patterns without an explicit format apply to the sdist only. To include package data in the wheel, specify format = "wheel", or use format = ["sdist", "wheel"] when the file belongs in both artifacts.
[tool.poetry]
include = [
{ path = "mypkg/data/*.json", format = ["sdist", "wheel"] }
]Poetry’s include takes priority over exclude, while exclude entries default to both formats. Since wheel contents are installed into site-packages, avoid broad wheel includes for documentation, tests, or changelogs unless they are genuinely needed at runtime. Refer to Poetry’s pyproject reference for the applicable configuration.
Build and verify the wheel
Configuration is only a selection rule; inspect the artifact that will actually be installed. The frontend invokes the backend, and the backend decides which project files to use during the build. The Python build documentation explains this frontend/backend relationship.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
- Confirm
[build-system].build-backendand consult that backend’s file-inclusion documentation. - Check that package discovery includes the package containing the data, especially when using a
srclayout or namespace package. - Build a wheel using the project’s normal build frontend and backend.
- Open the resulting
.whlarchive and check that the expected resource paths appear beneath the package directory. - Install the wheel into a clean environment and exercise the code that loads the resource. This catches cases where a file exists in the archive but the application’s resource path or loading logic is wrong.
Troubleshoot missing files
- The wrong setting has no effect: Recheck
[build-system].build-backend;[tool.*]sections belong to particular tools. - The data pattern appears correct but matches nothing: Confirm that the key is the importable package name, that package discovery includes it, and that nested paths and dotfiles are matched explicitly.
- The file is in the sdist but not the wheel: Remember that
MANIFEST.inselects sdist contents. Use package-relative setuptools data rules for runtime assets, or set Poetry’s include format to cover the wheel. - A rebuild appears to ignore a configuration or file-layout change: Setuptools notes that generated
build,dist, and*.egg-infoartifacts can be stale. Inspect or remove stale generated artifacts as appropriate, then rebuild and inspect the new wheel.
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.
