1.include_package_data¶

First, you can use theinclude_package_data keyword.

For example, if the package tree looks like this:

project_root_directory├── setup.py        # and/or setup.cfg, pyproject.toml└── src    └── mypkg        ├── __init__.py        ├── data1.rst        ├── data2.rst        ├── data1.txt        └── data2.txt

Whenat least one of the following conditions are met:

1. These files are included via theMANIFEST.in file,like so:

   includesrc/mypkg/*.txtincludesrc/mypkg/*.rst

2. They are being tracked by a revision control system such as Git, Mercurialor SVN,AND you have configured an appropriate plugin such assetuptools-scm orsetuptools-svn.(See the section below onAdding Support for Revision Control Systems for information on how to configure such plugins.)

then all the.txt and.rst files will be included intothe source distribution.

To further include them into thewheels, you can use theinclude_package_data keyword:

[tool.setuptools]# ...# By default, include-package-data is true in pyproject.toml,# so you do NOT have to specify this line.include-package-data=true[tool.setuptools.packages.find]where=["src"]

[options]# ...packages=find:package_dir==srcinclude_package_data=True[options.packages.find]where=src

fromsetuptoolsimportsetup,find_packagessetup(# ...,packages=find_packages(where="src"),package_dir={"":"src"},include_package_data=True)

2.package_data¶

By default,include_package_data considersall non.py files found insidethe package directory (src/mypkg in this case) as data files, and includes those thatsatisfy (at least) one of the above two conditions into the source distribution, andconsequently in the installation of your package.If you want finer-grained control over what files are included, then you can also usethepackage_data keyword.For example, if the package tree looks like this:

project_root_directory├── setup.py        # and/or setup.cfg, pyproject.toml└── src    └── mypkg        ├── __init__.py        ├── data1.rst        ├── data2.rst        ├── data1.txt        └── data2.txt

then you can use the following configuration to capture the.txt and.rst files asdata files:

[tool.setuptools.packages.find]where=["src"][tool.setuptools.package-data]mypkg=["*.txt","*.rst"]

[options]# ...packages=find:package_dir==src[options.packages.find]where=src[options.package_data]mypkg=*.txt*.rst

fromsetuptoolsimportsetup,find_packagessetup(# ...,packages=find_packages(where="src"),package_dir={"":"src"},package_data={"mypkg":["*.txt","*.rst"]})

Thepackage_data argument is a dictionary that maps from package names tolists of glob patterns. Note that the data files specified using thepackage_dataoption neither require to be included within aMANIFEST.infile, nor require to be added by a revision control system plugin.

If you have multiple top-level packages and a common pattern of data files for all thesepackages, for example:

project_root_directory├── setup.py        # and/or setup.cfg, pyproject.toml└── src    ├── mypkg1    │   ├── data1.rst    │   ├── data1.txt    │   └── __init__.py    └── mypkg2        ├── data2.txt        └── __init__.py

Here, both packagesmypkg1 andmypkg2 share a common pattern of having.txtdata files. However, onlymypkg1 has.rst data files. In such a case, if you want touse thepackage_data option, the following configuration will work:

[tool.setuptools.packages.find]where=["src"][tool.setuptools.package-data]"*"=["*.txt"]mypkg1=["data1.rst"]

[options]packages=find:package_dir==src[options.packages.find]where=src[options.package_data]*=*.txtmypkg1=data1.rst

fromsetuptoolsimportsetup,find_packagessetup(# ...,packages=find_packages(where="src"),package_dir={"":"src"},package_data={"":["*.txt"],"mypkg1":["data1.rst"]},)

Notice that if you list patterns inpackage_data under the empty string"" insetup.py, and the asterisk* insetup.cfg andpyproject.toml, thesepatterns are used to find files in every package. For example, we use"" or*to indicate that the.txt files from all packages should be captured as data files.These placeholders are treated as a special case,setuptoolsdo notsupport glob patterns on package names for this configuration(patterns are only supported on the file paths).Also note how we can continue to specify patterns for individual packages, i.e.we specify thatdata1.rst frommypkg1 alone should be captured as well.

3.exclude_package_data¶

Sometimes, theinclude_package_data orpackage_data options alonearen’t sufficient to precisely define what files you want included. For example,consider a scenario where you haveinclude_package_data=True, and you are usinga revision control system with an appropriate plugin.Sometimes developers add directory-specific marker files (such as.gitignore,.gitkeep,.gitattributes, or.hgignore), these files are probably beingtracked by the revision control system, and therefore by default they will beincluded when the package is installed.

Supposing you want to prevent these files from being included in theinstallation (they are not relevant to Python or the package), then you coulduse theexclude_package_data option:

[tool.setuptools.packages.find]where=["src"][tool.setuptools.exclude-package-data]mypkg=[".gitattributes"]

[options]# ...packages=find:package_dir==srcinclude_package_data=True[options.packages.find]where=src[options.exclude_package_data]mypkg=.gitattributes

fromsetuptoolsimportsetup,find_packagessetup(# ...,packages=find_packages(where="src"),package_dir={"":"src"},include_package_data=True,exclude_package_data={"mypkg":[".gitattributes"]},)

Theexclude_package_data option is a dictionary mapping package names tolists of wildcard patterns, just like thepackage_data option. And, justas with that option, you can use the empty string key"" insetup.py and theasterisk* insetup.cfg andpyproject.toml to match all top-level packages.

Any files that match these patterns will beexcluded from installation,even if they were listed inpackage_data or were included as a result of usinginclude_package_data.

Interplay between these keywords¶

Meanwhile, to further clarify the interplay between these three keywords,to include certain data file into the source distribution, the followinglogic condition has to be met:

MANIFEST.inor(package-dataandnotexclude-package-data)

In plain language, the file should be either:

1. included inMANIFEST.in; or

2. selected bypackage-data AND not excluded byexclude-package-data.

To include some data file into the.whl:

(notexclude-package-data)and((include-package-dataandMANIFEST.in)orpackage-data)

In other words, the file should not be excluded byexclude-package-data(highest priority), AND should be either:

1. selected bypackage-data; or

2. selected byMANIFEST.in AND useinclude-package-data=true.

Summary¶

In summary, the three options allow you to:

include_package_data

Accept all data files and directories matched byMANIFEST.in or added byaplugin.

package_data

Specify additional patterns to match files that may or maynot be matched byMANIFEST.inor added by aplugin.

exclude_package_data

Specify patterns for data files and directories that shouldnot beincluded when a package is installed, even if they would otherwise havebeen included due to the use of the preceding options.