Controlling files in the distribution¶

For the most common use cases,setuptools will automatically find out whichfiles are necessary for distributing the package. More precisely, the followingfiles are included in a source distribution by default:

• pure Python module files implied by thepy-modules andpackagesconfiguration parameters inpyproject.toml and/or equivalentinsetup.cfg/setup.py;

• C source files mentioned in theext_modules orlibrariessetup() arguments;

• Files that match the following glob patterns:tests/test*.py,test/test*.py;

• Scripts specified by thescripts-files configuration parameterinpyproject.toml orscripts insetup.py/setup.cfg;

• All files specified by thepackage-data anddata-filesconfiguration parameters inpyproject.toml and/or equivalentinsetup.cfg/setup.py;

• The file specified by thelicense_file option insetup.cfg;

• All files specified by thelicense-files configuration parameterinpyproject.toml and/or equivalent insetup.cfg/setup.py;note that if you don’t explicitly set this parameter,setuptoolswill include any files that match the following glob patterns:LICEN[CS]E*,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 versionofsetuptools. The behavior of older versions might differ.

However, when building more complex packages (e.g. packages that includenon-Python files, or that need to use custom C headers), you might find thatnot all files present in your project folder are included in packagedistribution archive.

If you are using aRevision Control System, such asgit ormercurial,and your source distributions only need to include files that you’retracking in revision control, you can use asetuptoolsplugin, such assetuptools-scm orsetuptools-svn to automatically include all tracked files into thesdist.

Alternatively, if you need finer control over the files (e.g. you don’t want todistributeCI/CD-related files) or you need automatically generated files,you can add aMANIFEST.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 tellsetuptools which files exactlyshould be part of thesdist (or not).

AMANIFEST.in file consists of commands, one per line, instructingsetuptools to add or remove some set of files from the sdist. The commandsare:

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

Directory patterns are relative to the root of the project directory; e.g.,graftexample* will include a directory namedexamples in theproject root but will not includedocs/examples/.

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

Commands are processed in the order they appear in theMANIFEST.infile. For example, given the commands:

grafttestsglobal-exclude*.py[cod]

the contents of the directory treetests will first be added to thesdist, 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 theopposite order, then*.pyc files etc. would be only be removed from whatwas already in the sdist before addingtests, and iftestshappened to contain any*.pyc files, they would end up included in thesdist because the exclusion happened before they were included.

An example ofMANIFEST.in for a simple project that organized according to asrc-layout is:

# MANIFEST.in -- just for illustrationgraftsrcgrafttestsgraftdocs# `-> adds all files inside a directoryincludetox.ini# `-> matches file paths relative to the root of the projectglobal-exclude*~*.py[cod]*.so# `-> matches file names (regardless of directory)

Once the correct files are present in thesdist, they can then be used bybinary extensions during the build process, or included in the finalwheel[1] if you configuresetuptools withinclude_package_data=True.

Caching and Troubleshooting¶

Setuptools automatically creates a few directories to host build artefacts andcache files, such asbuild,dist,*.egg-info. While cache isuseful to speed up incremental builds, in some edge cases it might becomestale. If you feel that caching is causing problems to your build, speciallyafter changes in configuration or in the directory/file structure., considerremovingbuild,dist,*.egg-info[3] before rebuilding orreinstalling your project.

You can think about the build process as two stages: first thesdistwill be created and then thewheel will be produced from thatsdist.

This happens because thesdist can contain files that are useful duringdevelopment or the build process itself, but not in runtime (e.g. tests,docs, examples, etc…).Thewheel, on the other hand, is a file format that has been optimizedand is ready to be unpacked into a running installation of Python orVirtual Environment.Therefore it only contains items that are required during runtime.

When working from an extracted sdist (e.g. for patching), you might also consider removingthePKG-INFO file to force its recreation.