1========
2Keywords
3========
4
5``name``
6    A string specifying the name of the package.
7
8``version``
9    A string specifying the version number of the package.
10
11``description``
12    A string describing the package in a single line.
13
14``long_description``
15    A string providing a longer description of the package.
16
17``long_description_content_type``
18    A string specifying the content type is used for the ``long_description``
19    (e.g. ``text/markdown``)
20
21``author``
22    A string specifying the author of the package.
23
24``author_email``
25    A string specifying the email address of the package author.
26
27``maintainer``
28    A string specifying the name of the current maintainer, if different from
29    the author. Note that if the maintainer is provided, setuptools will use it
30    as the author in ``PKG-INFO``.
31
32``maintainer_email``
33    A string specifying the email address of the current maintainer, if
34    different from the author.
35
36``url``
37    A string specifying the URL for the package homepage.
38
39``download_url``
40    A string specifying the URL to download the package.
41
42``packages``
43    A list of strings specifying the packages that setuptools will manipulate.
44
45``py_modules``
46    A list of strings specifying the modules that setuptools will manipulate.
47
48``scripts``
49    A list of strings specifying the standalone script files to be built and
50    installed.
51
52``ext_package``
53    A string specifying the base package name for the extensions provided by
54    this package.
55
56``ext_modules``
57    A list of instances of ``setuptools.Extension`` providing the list of
58    Python extensions to be built.
59
60``classifiers``
61    A list of strings describing the categories for the package.
62
63``distclass``
64    A subclass of ``Distribution`` to use.
65
66``script_name``
67    A string specifying the name of the setup.py script -- defaults to
68    ``sys.argv[0]``
69
70``script_args``
71    A list of strings defining the arguments to supply to the setup script.
72
73``options``
74    A dictionary providing the default options for the setup script.
75
76``license``
77    A string specifying the license of the package.
78
79``license_file``
80
81    .. warning::
82        ``license_file`` is deprecated. Use ``license_files`` instead.
83
84``license_files``
85
86    A list of glob patterns for license related files that should be included.
87    If neither ``license_file`` nor ``license_files`` is specified, this option
88    defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``.
89
90``keywords``
91    A list of strings or a comma-separated string providing descriptive
92    meta-data. See: `PEP 0314`_.
93
94.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/
95
96``platforms``
97    A list of strings or comma-separated string.
98
99``cmdclass``
100    A dictionary providing a mapping of command names to ``Command``
101    subclasses.
102
103``data_files``
104
105    .. warning::
106        ``data_files`` is deprecated. It does not work with wheels, so it
107        should be avoided.
108
109    A list of strings specifying the data files to install.
110
111``package_dir``
112    A dictionary providing a mapping of package to directory names.
113
114``requires``
115
116   .. warning::
117      ``requires`` is superseded by ``install_requires`` and should not be used
118      anymore.
119
120``obsoletes``
121
122   .. warning::
123      ``obsoletes`` is currently ignored by ``pip``.
124
125   List of strings describing packages which this package renders obsolete,
126   meaning that the two projects should not be installed at the same time.
127
128   Version declarations can be supplied. Version numbers must be in the format
129   specified in Version specifiers (e.g. ``foo (<3.0)``).
130
131   This field may be followed by an environment marker after a semicolon (e.g.
132   ``foo; os_name == "posix"``)
133
134   The most common use of this field will be in case a project name changes,
135   e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install
136   Torqued Python, the Gorgon distribution should be removed.
137
138``provides``
139
140   .. warning::
141      ``provides`` is currently ignored by ``pip``.
142
143   List of strings describing package- and virtual package names contained
144   within this package.
145
146   A package may provide additional names, e.g. to indicate that multiple
147   projects have been bundled together. For instance, source distributions of
148   the ZODB project have historically included the transaction project, which
149   is now available as a separate distribution. Installing such a source
150   distribution satisfies requirements for both ZODB and transaction.
151
152   A package may also provide a “virtual” project name, which does not
153   correspond to any separately-distributed project: such a name might be used
154   to indicate an abstract capability which could be supplied by one of
155   multiple projects. E.g., multiple projects might supply RDBMS bindings for
156   use by a given ORM: each project might declare that it provides
157   ORM-bindings, allowing other projects to depend only on having at most one
158   of them installed.
159
160   A version declaration may be supplied and must follow the rules described in
161   Version specifiers. The distribution’s version number will be implied if
162   none is specified (e.g. ``foo (<3.0)``).
163
164   Each package may be followed by an environment marker after a semicolon
165   (e.g. ``foo; os_name == "posix"``).
166
167.. Below are setuptools keywords, above are distutils
168
169``include_package_data``
170    If set to ``True``, this tells ``setuptools`` to automatically include any
171    data files it finds inside your package directories that are specified by
172    your ``MANIFEST.in`` file.  For more information, see the section on
173    :ref:`Including Data Files`.
174
175``exclude_package_data``
176    A dictionary mapping package names to lists of glob patterns that should
177    be *excluded* from your package directories.  You can use this to trim back
178    any excess files included by ``include_package_data``.  For a complete
179    description and examples, see the section on :ref:`Including Data Files`.
180
181``package_data``
182    A dictionary mapping package names to lists of glob patterns.  For a
183    complete description and examples, see the section on :ref:`Including Data
184    Files`.  You do not need to use this option if you are using
185    ``include_package_data``, unless you need to add e.g. files that are
186    generated by your setup script and build process.  (And are therefore not
187    in source control or are files that you don't want to include in your
188    source distribution.)
189
190``zip_safe``
191    A boolean (True or False) flag specifying whether the project can be
192    safely installed and run from a zip file.  If this argument is not
193    supplied, the ``bdist_egg`` command will have to analyze all of your
194    project's contents for possible problems each time it builds an egg.
195
196``install_requires``
197    A string or list of strings specifying what other distributions need to
198    be installed when this one is.  See the section on :ref:`Declaring
199    Dependencies` for details and examples of the format of this argument.
200
201``entry_points``
202    A dictionary mapping entry point group names to strings or lists of strings
203    defining the entry points.  Entry points are used to support dynamic
204    discovery of services or plugins provided by a project.  See :ref:`Dynamic
205    Discovery of Services and Plugins` for details and examples of the format
206    of this argument.  In addition, this keyword is used to support
207    :ref:`Automatic Script Creation <entry_points>`.
208
209``extras_require``
210    A dictionary mapping names of "extras" (optional features of your project)
211    to strings or lists of strings specifying what other distributions must be
212    installed to support those features.  See the section on :ref:`Declaring
213    Dependencies` for details and examples of the format of this argument.
214
215``python_requires``
216    A string corresponding to a version specifier (as defined in PEP 440) for
217    the Python version, used to specify the Requires-Python defined in PEP 345.
218
219``setup_requires``
220
221    .. warning::
222        Using ``setup_requires`` is discouraged in favor of `PEP-518`_
223
224    A string or list of strings specifying what other distributions need to
225    be present in order for the *setup script* to run.  ``setuptools`` will
226    attempt to obtain these (even going so far as to download them using
227    ``EasyInstall``) before processing the rest of the setup script or commands.
228    This argument is needed if you are using distutils extensions as part of
229    your build process; for example, extensions that process setup() arguments
230    and turn them into EGG-INFO metadata files.
231
232    (Note: projects listed in ``setup_requires`` will NOT be automatically
233    installed on the system where the setup script is being run.  They are
234    simply downloaded to the ./.eggs directory if they're not locally available
235    already.  If you want them to be installed, as well as being available
236    when the setup script is run, you should add them to ``install_requires``
237    **and** ``setup_requires``.)
238
239.. _PEP-518: http://www.python.org/dev/peps/pep-0518/
240
241``dependency_links``
242
243    .. warning::
244        ``dependency_links`` is deprecated. It is not supported anymore by pip.
245
246    A list of strings naming URLs to be searched when satisfying dependencies.
247    These links will be used if needed to install packages specified by
248    ``setup_requires`` or ``tests_require``.  They will also be written into
249    the egg's metadata for use by tools like EasyInstall to use when installing
250    an ``.egg`` file.
251
252``namespace_packages``
253    A list of strings naming the project's "namespace packages".  A namespace
254    package is a package that may be split across multiple project
255    distributions.  For example, Zope 3's ``zope`` package is a namespace
256    package, because subpackages like ``zope.interface`` and ``zope.publisher``
257    may be distributed separately.  The egg runtime system can automatically
258    merge such subpackages into a single parent package at runtime, as long
259    as you declare them in each project that contains any subpackages of the
260    namespace package, and as long as the namespace package's ``__init__.py``
261    does not contain any code other than a namespace declaration.  See the
262    section on :ref:`Namespace Packages` for more information.
263
264``test_suite``
265    A string naming a ``unittest.TestCase`` subclass (or a package or module
266    containing one or more of them, or a method of such a subclass), or naming
267    a function that can be called with no arguments and returns a
268    ``unittest.TestSuite``.  If the named suite is a module, and the module
269    has an ``additional_tests()`` function, it is called and the results are
270    added to the tests to be run.  If the named suite is a package, any
271    submodules and subpackages are recursively added to the overall test suite.
272
273    Specifying this argument enables use of the :ref:`test` command to run the
274    specified test suite, e.g. via ``setup.py test``.  See the section on the
275    :ref:`test` command below for more details.
276
277    New in 41.5.0: Deprecated the test command.
278
279``tests_require``
280    If your project's tests need one or more additional packages besides those
281    needed to install it, you can use this option to specify them.  It should
282    be a string or list of strings specifying what other distributions need to
283    be present for the package's tests to run.  When you run the ``test``
284    command, ``setuptools`` will  attempt to obtain these (even going
285    so far as to download them using ``EasyInstall``).  Note that these
286    required projects will *not* be installed on the system where the tests
287    are run, but only downloaded to the project's setup directory if they're
288    not already installed locally.
289
290    New in 41.5.0: Deprecated the test command.
291
292.. _test_loader:
293
294``test_loader``
295    If you would like to use a different way of finding tests to run than what
296    setuptools normally uses, you can specify a module name and class name in
297    this argument.  The named class must be instantiable with no arguments, and
298    its instances must support the ``loadTestsFromNames()`` method as defined
299    in the Python ``unittest`` module's ``TestLoader`` class.  Setuptools will
300    pass only one test "name" in the ``names`` argument: the value supplied for
301    the ``test_suite`` argument.  The loader you specify may interpret this
302    string in any way it likes, as there are no restrictions on what may be
303    contained in a ``test_suite`` string.
304
305    The module name and class name must be separated by a ``:``.  The default
306    value of this argument is ``"setuptools.command.test:ScanningLoader"``.  If
307    you want to use the default ``unittest`` behavior, you can specify
308    ``"unittest:TestLoader"`` as your ``test_loader`` argument instead.  This
309    will prevent automatic scanning of submodules and subpackages.
310
311    The module and class you specify here may be contained in another package,
312    as long as you use the ``tests_require`` option to ensure that the package
313    containing the loader class is available when the ``test`` command is run.
314
315    New in 41.5.0: Deprecated the test command.
316
317``eager_resources``
318    A list of strings naming resources that should be extracted together, if
319    any of them is needed, or if any C extensions included in the project are
320    imported.  This argument is only useful if the project will be installed as
321    a zipfile, and there is a need to have all of the listed resources be
322    extracted to the filesystem *as a unit*.  Resources listed here
323    should be '/'-separated paths, relative to the source root, so to list a
324    resource ``foo.png`` in package ``bar.baz``, you would include the string
325    ``bar/baz/foo.png`` in this argument.
326
327    If you only need to obtain resources one at a time, or you don't have any C
328    extensions that access other files in the project (such as data files or
329    shared libraries), you probably do NOT need this argument and shouldn't
330    mess with it.  For more details on how this argument works, see the section
331    below on :ref:`Automatic Resource Extraction`.
332
333``project_urls``
334    An arbitrary map of URL names to hyperlinks, allowing more extensible
335    documentation of where various resources can be found than the simple
336    ``url`` and ``download_url`` options provide.
337