Controlling files in the distribution

For the most common use cases, setuptools will automatically find out which files are necessary for distributing the package. These include all pure Python modules in the py_modules or packages configuration, and the C sources (but not C headers) listed as part of extensions when creating a source distribution (or “sdist”).

However, when building more complex packages (e.g. packages that include non-Python files, or that need to use custom C headers), you might find that not all files present in your project folder are included in package distribution archive.

If you are using a Revision Control System, such as git or mercurial, and your source distributions only need to include files that you’re tracking in revision control, you can use a setuptools plugin, such as setuptools-scm or setuptools-svn to automatically include all tracked files into the sdist.

Alternatively, if you need finer control over the files (e.g. you don’t want to distribute CI/CD-related files) or you need automatically generated files, you can add a MANIFEST.in file at the root of your project, to specify any files that the default file location algorithm doesn’t catch.

This file contains instructions that tell setuptools which files exactly should be part of the sdist (or not). A comprehensive guide to MANIFEST.in syntax is available at the PyPA’s Packaging User Guide.

Attention

Please note that setuptools supports the MANIFEST.in, and not MANIFEST (no extension). Any documentation, tutorial or example that recommends using MANIFEST (no extension) is likely outdated.

Tip

The MANIFEST.in file contains commands that allow you to discover and manipulate lists of files. There are many commands that can be used with different objectives, but you should try to not make your MANIFEST.in file too fine grained.

A good idea is to start with a graft command (to add all files inside a set of directories) and then fine tune the file selection by removing the excess or adding isolated files.

An example of MANIFEST.in for a simple project that organized according to a src-layout is:

# MANIFEST.in -- just for illustration
graft src
graft tests
graft docs
# `-> adds all files inside a directory

include tox.ini
# `-> matches file paths relative to the root of the project

global-exclude *~ *.py[cod] *.so
# `-> matches file names (regardless of directory)

Once the correct files are present in the sdist, they can then be used by binary extensions during the build process, or included in the final wheel [1] if you configure setuptools with include_package_data=True.

Important

Please note that, when using include_package_data=True, only files inside the package directory are included in the final wheel, by default.

So for example, if you create a Python project that uses setuptools-scm and have a tests directory outside of the package folder, the tests directory will be present in the sdist but not in the wheel [2].

See Data Files Support for more information.

---

[1]

You can think about the build process as two stages: first the sdist will be created and then the wheel will be produced from that sdist.

[2]

This happens because the sdist can contain files that are useful during development or the build process itself, but not in runtime (e.g. tests, docs, examples, etc…). The wheel, on the other hand, is a file format that has been optimized and is ready to be unpacked into a running installation of Python or Virtual Environment. Therefore it only contains items that are required during runtime.