Keywords¶

The following are keywordssetuptools.setup() accepts.They allow configuring the build process for a Python distribution or addingmetadata via asetup.py script placed at the root of your project.All of them are optional; you do not have to supply them unless you need theassociatedsetuptools feature.

Metadata and configuration supplied viasetup() is complementary to (andmay be overwritten by) the information present insetup.cfg andpyproject.toml.Some important metadata, such asname andversion, may assumea defaultdegenerate value if not specified.

Users are strongly encouraged to use a declarative config either viasetup.cfg orpyproject.toml and only rely onsetup.py if they need totap into special behaviour that requires scripting (such as building Cextensions).

fromsetuptoolsimportsetupsetup()

name

A string specifying the name of the package.

version

A string specifying the version number of the package.

description

A string describing the package in a single line.

long_description

A string providing a longer description of the package.

long_description_content_type

A string specifying the content type is used for thelong_description(e.g.text/markdown)

author

A string specifying the author of the package.

author_email

A string specifying the email address of the package author.

maintainer

A string specifying the name of the current maintainer, if different fromthe author. Note that if the maintainer is provided, setuptools will use itas the author inPKG-INFO.

maintainer_email

A string specifying the email address of the current maintainer, ifdifferent from the author.

url

A string specifying the URL for the package homepage.

download_url

A string specifying the URL to download the package.

packages

A list of strings specifying the packages that setuptools will manipulate.

py_modules

A list of strings specifying the modules that setuptools will manipulate.

scripts

A list of strings specifying the standalone script files to be built andinstalled.

ext_package

A string specifying the base package name for the extensions provided bythis package.

ext_modules

A list of instances ofsetuptools.Extension providing the list ofPython extensions to be built.

classifiers

A list of strings describing the categories for the package.

distclass

A subclass ofDistribution to use.

script_name

A string specifying the name of the setup.py script – defaults tosys.argv[0]

script_args

A list of strings defining the arguments to supply to the setup script.

options

A dictionary providing the default options for the setup script.

license

A string specifying the license of the package.

license_file

Warning

license_file is deprecated. Uselicense_files instead.

license_files

A list of glob patterns for license related files that should be included.If neitherlicense_file norlicense_files is specified, this optiondefaults toLICEN[CS]E*,COPYING*,NOTICE*, andAUTHORS*.

keywords

A list of strings or a comma-separated string providing descriptivemeta-data. See:Core Metadata Specifications.

platforms

A list of strings or comma-separated string.

cmdclass

A dictionary providing a mapping of command names toCommandsubclasses.

data_files

Attention

DISCOURAGED - This is an advanced feature and it isnot intended to work with absolute paths.All files listed indata_files will be installed in paths relativeto a directory decided by the package installer (e.g.pip).This usually results in nesting under a virtual environment.WeSTRONGLY ADVISE AGAINST using this setting for things likeapplication launchers, desktop files or anything that requiressystem-wide installation[1], unless you have extensiveexperience in Python packaging and have carefully considered all thedrawbacks, limitations and problems of this method.Also note that this feature is providedas is with no plans offurther changes.

Tip

SeeData Files Support for an alternative method that uses thepackage directory itself and works well withimportlib.resources,or consider using libraries such asplatformdirs for creatingand managing files at runtime (i.e.,not during the installation).

A sequence of(directory,files) pairs specifying the data files to install(directory is astr,files is a sequence ofstr).Each(directory,files) pair in the sequence specifies the installation directoryand the files to install there.

package_dir

A dictionary that maps package names (as they will beimported by the end-users) into directory paths (that actually exist in theproject’s source tree). This configuration has two main purposes:

1. To effectively “rename” paths when building your package.For example,package_dir={"mypkg":"dir1/dir2/code_for_mypkg"}will instruct setuptools to copy thedir1/dir2/code_for_mypkg/... filesasmypkg/... when building the finalwheel distribution.

   Attention

   While it ispossible to specify arbitrary mappings, developers areSTRONGLY ADVISED AGAINST that. They should try as much as possibleto keep the directory names and hierarchy identical to the way they willappear in the final wheel, only deviating when absolutely necessary.

2. To indicate that the relevant code is entirely contained insidea specific directory (instead of directly placed under the project’s root).In this case, a special key is required (the empty string,""),for example:package_dir={"":"<nameofthecontainerdirectory>"}.All the directories inside the container directory will be copieddirectly into the finalwheel distribution, but thecontainer directory itself will not.

   This practice is very common in the community to help separate thepackage implementation from auxiliary files (e.g. CI configuration files),and is referred to assrc-layout, because the containerdirectory is commonly namedsrc.

All paths inpackage_dir must be relative to the project root directoryand use a forward slash (/) as path separator regardless of theoperating system.

Tip

When usingpackage discoverytogether withsetup.cfg orpyproject.toml, it is very likelythat you don’t need to specify a value forpackage_dir. Please havea look at the definitions ofsrc-layout andflat-layout tolearn common practices on how to design a project’s directory structureand minimise the amount of configuration that is needed.

requires

Warning

requires is superseded byinstall_requires and should not be usedanymore.

obsoletes

Warning

obsoletes is currently ignored bypip.

List of strings describing packages which this package renders obsolete,meaning that the two projects should not be installed at the same time.

Version declarations can be supplied. Version numbers must be in the formatspecified in Version specifiers (e.g.foo(<3.0)).

This field may be followed by an environment marker after a semicolon (e.g.foo;os_name=="posix")

The most common use of this field will be in case a project name changes,e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you installTorqued Python, the Gorgon distribution should be removed.

provides

Warning

provides is currently ignored bypip.

List of strings describing package- and virtual package names containedwithin this package.

A package may provide additional names, e.g. to indicate that multipleprojects have been bundled together. For instance, source distributions ofthe ZODB project have historically included the transaction project, whichis now available as a separate distribution. Installing such a sourcedistribution satisfies requirements for both ZODB and transaction.

A package may also provide a “virtual” project name, which does notcorrespond to any separately-distributed project: such a name might be usedto indicate an abstract capability which could be supplied by one ofmultiple projects. E.g., multiple projects might supply RDBMS bindings foruse by a given ORM: each project might declare that it providesORM-bindings, allowing other projects to depend only on having at most oneof them installed.

A version declaration may be supplied and must follow the rules described inVersion specifiers. The distribution’s version number will be implied ifnone is specified (e.g.foo(<3.0)).

Each package may be followed by an environment marker after a semicolon(e.g.foo;os_name=="posix").

include_package_data

If set toTrue, this tellssetuptools to automatically include anydata files it finds inside your package directories that are specified byyourMANIFEST.in file. For more information, see the section onIncluding Data Files.

exclude_package_data

A dictionary mapping package names to lists of glob patterns that shouldbeexcluded from your package directories. You can use this to trim backany excess files included byinclude_package_data. For a completedescription and examples, see the section onIncluding Data Files.

package_data

A dictionary mapping package names to lists of glob patterns. For acomplete description and examples, see the section onIncluding Data Files. You do not need to use this option if you are usinginclude_package_data, unless you need to add e.g. files that aregenerated by your setup script and build process. (And are therefore notin source control or are files that you don’t want to include in yoursource distribution.)

zip_safe

A boolean (True or False) flag specifying whether the project can besafely installed and run from a zip file. If this argument is notsupplied, thebdist_egg command will have to analyze all of yourproject’s contents for possible problems each time it builds an egg.

install_requires

A string or list of strings specifying what other distributions need tobe installed when this one is. See the section onDeclaring required dependency for details and examples of the format of this argument.

entry_points

A dictionary mapping entry point group names to strings or lists of stringsdefining the entry points. Entry points are used to support dynamicdiscovery of services or plugins provided by a project. SeeAdvertising Behavior for details and examples of the formatof this argument. In addition, this keyword is used to supportAutomatic Script Creation.

extras_require

A dictionary mapping names of “extras” (optional features of your project)to strings or lists of strings specifying what other distributions must beinstalled to support those features. See the section onDeclaring required dependency for details and examples of the format of this argument.

python_requires

A string corresponding to a version specifier (as defined in PEP 440) forthe Python version, used to specify the Requires-Python defined in PEP 345.

setup_requires

Warning

Usingsetup_requires is discouraged in favor ofPEP 518.

A string or list of strings specifying what other distributions need tobe present in order for thesetup script to run.setuptools willattempt to obtain these before processing therest of the setup script or commands. This argument is needed if youare using distutils extensions as part of your build process; forexample, extensions that process setup() arguments and turn them intoEGG-INFO metadata files.

(Note: projects listed insetup_requires will NOT be automaticallyinstalled on the system where the setup script is being run. They aresimply downloaded to the ./.eggs directory if they’re not locally availablealready. If you want them to be installed, as well as being availablewhen the setup script is run, you should add them toinstall_requiresandsetup_requires.)

dependency_links

Warning

dependency_links is deprecated. It is not supported anymore by pip.

A list of strings naming URLs to be searched when satisfying dependencies.These links will be used if needed to install packages specified bysetup_requires ortests_require. They will also be written intothe egg’s metadata for use during install by tools that support them.

namespace_packages

Warning

Thenamespace_packages implementation relies onpkg_resources.However,pkg_resources has some undesirable behaviours, andSetuptools intends to obviate its usage in the future. Therefore,namespace_packages was deprecated in favor of native/implicitnamespaces (PEP 420). Checkthe Python Packaging User Guide for more information.

A list of strings naming the project’s “namespace packages”. A namespacepackage is a package that may be split across multiple projectdistributions. For example, Zope 3’szope package is a namespacepackage, because subpackages likezope.interface andzope.publishermay be distributed separately. The egg runtime system can automaticallymerge such subpackages into a single parent package at runtime, as longas you declare them in each project that contains any subpackages of thenamespace package, and as long as the namespace package’s__init__.pydoes not contain any code other than a namespace declaration. See thesection onFinding namespace packages for more information.

test_suite

A string naming aunittest.TestCase subclass (or a package or modulecontaining one or more of them, or a method of such a subclass), or naminga function that can be called with no arguments and returns aunittest.TestSuite. If the named suite is a module, and the modulehas anadditional_tests() function, it is called and the results areadded to the tests to be run. If the named suite is a package, anysubmodules and subpackages are recursively added to the overall test suite.

Specifying this argument enables use of thetest command to run thespecified test suite, e.g. viasetup.pytest. See the section on thetest command below for more details.

Warning

Deprecated since version 41.5.0:The test command will be removed in a future version ofsetuptools,alongside any test configuration parameter.

tests_require

If your project’s tests need one or more additional packages besides thoseneeded to install it, you can use this option to specify them. It shouldbe a string or list of strings specifying what other distributions need tobe present for the package’s tests to run. When you run thetestcommand,setuptools will attempt to obtain these.Note that these required projects willnot be installed onthe system where the tests are run, but only downloaded to the project’s setupdirectory if they’re not already installed locally.

Warning

Deprecated since version 41.5.0:The test command will be removed in a future version ofsetuptools,alongside any test configuration parameter.

test_loader

If you would like to use a different way of finding tests to run than whatsetuptools normally uses, you can specify a module name and class name inthis argument. The named class must be instantiable with no arguments, andits instances must support theloadTestsFromNames() method as definedin the Pythonunittest module’sTestLoader class. Setuptools willpass only one test “name” in thenames argument: the value supplied forthetest_suite argument. The loader you specify may interpret thisstring in any way it likes, as there are no restrictions on what may becontained in atest_suite string.

The module name and class name must be separated by a:. The defaultvalue of this argument is"setuptools.command.test:ScanningLoader". Ifyou want to use the defaultunittest behavior, you can specify"unittest:TestLoader" as yourtest_loader argument instead. Thiswill prevent automatic scanning of submodules and subpackages.

The module and class you specify here may be contained in another package,as long as you use thetests_require option to ensure that the packagecontaining the loader class is available when thetest command is run.

Warning

Deprecated since version 41.5.0:The test command will be removed in a future version ofsetuptools,alongside any test configuration parameter.

eager_resources

A list of strings naming resources that should be extracted together, ifany of them is needed, or if any C extensions included in the project areimported. This argument is only useful if the project will be installed asa zipfile, and there is a need to have all of the listed resources beextracted to the filesystemas a unit. Resources listed hereshould be ‘/’-separated paths, relative to the source root, so to list aresourcefoo.png in packagebar.baz, you would include the stringbar/baz/foo.png in this argument.

If you only need to obtain resources one at a time, or you don’t have any Cextensions that access other files in the project (such as data files orshared libraries), you probably do NOT need this argument and shouldn’tmess with it. For more details on how this argument works, see the sectionbelow onAutomatic Resource Extraction.

project_urls

An arbitrary map of URL names to hyperlinks, allowing more extensibledocumentation of where various resources can be found than the simpleurl anddownload_url options provide.

It is common for developers to attempt usingdata_files for manpages.Please note however that depending on the installation directory, this willnot work out of the box - often the final user is required to change theMANPATH environment variable.See thediscussion in Python discourse for more details.