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
andpackages
setup()
argumentsall C source files mentioned in the
ext_modules
orlibraries
setup()
argumentsscripts specified by the
scripts
setup()
argumentall files specified by the
package_data
anddata_files
setup()
argumentsthe file specified by the
license_file
option insetup.cfg
(setuptools 40.8.0+)all files specified by the
license_files
option insetup.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 |
---|---|
|
Add all files matching any of the listed patterns |
|
Remove all files matching any of the listed patterns |
|
Add all files under directories matching |
|
Remove all files under directories matching |
|
Add all files anywhere in the source tree matching any of the listed patterns |
|
Remove all files anywhere in the source tree matching any of the listed patterns |
|
Add all files under directories matching |
|
Remove all files under directories matching |
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.