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
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
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.
Please note that
setuptools supports the
MANIFEST (no extension). Any documentation, tutorial or example
that recommends using
MANIFEST (no extension) is likely outdated.
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
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
# 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  if you configure
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
tests directory will be present in the
sdist but not in the
See Data Files Support for more information.