Controlling files in the distribution#
For the most common use cases, setuptools
will automatically find out which
files are necessary for distributing the package. More precisely, the following
files are included in a source distribution by default:
pure Python module files implied by the
py-modules
andpackages
configuration parameters inpyproject.toml
and/or equivalent insetup.cfg
/setup.py
;C source files mentioned in the
ext_modules
orlibraries
setup()
arguments;Files that match the following glob patterns:
tests/test*.py
,test/test*.py
;Scripts specified by the
scripts-files
configuration parameter inpyproject.toml
orscripts
insetup.py
/setup.cfg
;All files specified by the
package-data
anddata-files
configuration parameters inpyproject.toml
and/or equivalent insetup.cfg
/setup.py
;The file specified by the
license_file
option insetup.cfg
;All files specified by the
license-files
configuration parameter inpyproject.toml
and/or equivalent insetup.cfg
/setup.py
; note that if you don’t explicitly set this parameter,setuptools
will include any files that match the following glob patterns:LICENSE*
,LICENCE*
,COPYING*
,NOTICE*
,AUTHORS**
;pyproject.toml
;setup.cfg
;setup.py
;README
,README.txt
,README.rst
orREADME.md
;MANIFEST.in
Please note that the list above is guaranteed to work with the last stable version
of setuptools
. The behavior of older versions might differ.
Note
New in version v68.3.0: setuptools
will attempt to include type information files
by default in the distribution
(.pyi
and py.typed
, as specified in PEP 561).
Please note however that this feature is EXPERIMENTAL and may change in the future.
If you have .pyi
and py.typed
files in your project, but do not
wish to distribute them, you can opt out by setting
exclude-package-data to remove them.
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).
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.
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 (Files must be given as paths relative to the root of the project) |
|
Remove all files matching any of the listed patterns (Files must be given as paths relative to the root of the project) |
|
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 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.
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.