Including files in source distributions with MANIFEST.in

When building a source distribution for your package, by default only a minimal set of files are included. You may find yourself wanting to include extra files in the source distribution, such as an authors/contributors file, a docs/ directory, or a directory of data files used for testing purposes. There may even be extra files that you need to include; for example, if your setup.py computes your project’s long_description by reading from both a README and a changelog file, you’ll need to include both those files in the sdist so that people that build or install from the sdist get the correct results.

Adding & removing files to & from the source distribution is done by writing a MANIFEST.in file at the project root.

How files are included in an sdist

The following files are included in a source distribution by default:

• all Python source files implied by the py_modules and packages setup() arguments

• all C source files mentioned in the ext_modules or libraries setup() arguments

• scripts specified by the scripts setup() argument

• all files specified by the package_data and data_files setup() arguments

• the file specified by the license_file option in setup.cfg (setuptools 40.8.0+)

• all files specified by the license_files option in setup.cfg (setuptools 42.0.0+)

• all files matching the pattern test/test*.py

• setup.py (or whatever you called your setup script)

• setup.cfg

• README

• README.txt

• README.rst (Python 3.7+ or setuptools 0.6.27+)

• README.md (setuptools 36.4.0+)

• pyproject.toml (setuptools 43.0.0+)

• MANIFEST.in

After adding the above files to the sdist, the commands in MANIFEST.in (if such a file exists) are executed in order to add and remove further files to & from the sdist. Default files can even be removed from the sdist with the appropriate MANIFEST.in command.

After processing the MANIFEST.in file, setuptools removes the build/ directory as well as any directories named RCS, CVS, or .svn from the sdist, and it adds a PKG-INFO file and an *.egg-info directory. This behavior cannot be changed with MANIFEST.in.

MANIFEST.in commands

A MANIFEST.in file consists of commands, one per line, instructing setuptools to add or remove some set of files from the sdist. The commands are:

Command	Description
include pat1 pat2 ...	Include all files matching any of the listed patterns
exclude pat1 pat2 ...	Exclude all files matching any of the listed patterns
recursive-include dir-pattern pat1 pat2 ...	Include all files under directories matching dir-pattern that match any of the listed patterns
recursive-exclude dir-pattern pat1 pat2 ...	Exclude all files under directories matching dir-pattern that match any of the listed patterns
global-include pat1 pat2 ...	Include all files anywhere in the source tree matching any of the listed patterns
global-exclude pat1 pat2 ...	Exclude all files anywhere in the source tree matching any of the listed patterns
graft dir-pattern	Include all files under directories matching dir-pattern
prune dir-pattern	Exclude all files under directories matching dir-pattern

The patterns here are glob-style patterns: * matches zero or more regular filename characters (on Unix, everything except forward slash; on Windows, everything except backslash and colon); ? matches a single regular filename character, and [chars] matches any one of the characters between the square brackets (which may contain character ranges, e.g., [a-z] or [a-fA-F0-9]). Setuptools also has undocumented support for ** matching zero or more characters including forward slash, backslash, and colon.

Directory patterns are relative to the root of the project directory; e.g., graft example* will include a directory named examples in the project root but will not include docs/examples/.

File & directory names in MANIFEST.in should be /-separated; setuptools will automatically convert the slashes to the local platform’s appropriate directory separator.

Commands are processed in the order they appear in the MANIFEST.in file. For example, given the commands:

graft tests
global-exclude *.py[cod]

the contents of the directory tree tests will first be added to the sdist, and then after that all files in the sdist with a .pyc, .pyo, or .pyd extension will be removed from the sdist. If the commands were in the opposite order, then *.pyc files etc. would be only be removed from what was already in the sdist before adding tests, and if tests happened to contain any *.pyc files, they would end up included in the sdist because the exclusion happened before they were included.