Installing setuptools

To install the latest version of setuptools, use:

pip install --upgrade setuptools

Refer to Installing Packages guide for more information.

Basic Use

For basic use of setuptools, just import things from setuptools instead of the distutils. Here’s a minimal setup script using setuptools:

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
)

As you can see, it doesn’t take much to use setuptools in a project. Run that script in your project folder, alongside the Python packages you have developed.

Invoke that script to produce distributions and automatically include all packages in the directory where the setup.py lives. See the Command Reference section below to see what commands you can give to this setup script. For example, to produce a source distribution, simply invoke:

setup.py sdist

Of course, before you release your project to PyPI, you’ll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts:

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
    scripts=["say_hello.py"],

    # Project uses reStructuredText, so ensure that the docutils get
    # installed or upgraded on the target machine
    install_requires=["docutils>=0.3"],

    package_data={
        # If any package contains *.txt or *.rst files, include them:
        "": ["*.txt", "*.rst"],
        # And include any *.msg files found in the "hello" package, too:
        "hello": ["*.msg"],
    },

    # metadata to display on PyPI
    author="Me",
    author_email="me@example.com",
    description="This is an Example Package",
    keywords="hello world example examples",
    url="http://example.com/HelloWorld/",   # project home page, if any
    project_urls={
        "Bug Tracker": "https://bugs.example.com/HelloWorld/",
        "Documentation": "https://docs.example.com/HelloWorld/",
        "Source Code": "https://code.example.com/HelloWorld/",
    },
    classifiers=[
        "License :: OSI Approved :: Python Software Foundation License"
    ]

    # could also include long_description, download_url, etc.
)

In the sections that follow, we’ll explain what most of these setup() arguments do (except for the metadata ones), and the various ways you might use them in your own project(s).

New and Changed setup() Keywords

The following keyword arguments to setup() are added or changed by setuptools. All of them are optional; you do not have to supply them unless you need the associated setuptools feature.

include_package_data

If set to True, this tells setuptools to automatically include any data files it finds inside your package directories that are specified by your MANIFEST.in file. For more information, see the section below on Including Data Files.

exclude_package_data

A dictionary mapping package names to lists of glob patterns that should be excluded from your package directories. You can use this to trim back any excess files included by include_package_data. For a complete description and examples, see the section below on Including Data Files.

package_data

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

zip_safe

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

install_requires

A string or list of strings specifying what other distributions need to be installed when this one is. See the section below on Declaring Dependencies for details and examples of the format of this argument.

entry_points

A dictionary mapping entry point group names to strings or lists of strings defining the entry points. Entry points are used to support dynamic discovery of services or plugins provided by a project. See Dynamic Discovery of Services and Plugins for details and examples of the format of this argument. In addition, this keyword is used to support Automatic 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 be installed to support those features. See the section below on Declaring Dependencies for details and examples of the format of this argument.

python_requires

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

setup_requires

A string or list of strings specifying what other distributions need to be present in order for the setup script to run. setuptools will attempt to obtain these (using pip if available) before processing the rest of the setup script or commands. This argument is needed if you are using distutils extensions as part of your build process; for example, extensions that process setup() arguments and turn them into EGG-INFO metadata files.

(Note: projects listed in setup_requires will NOT be automatically installed on the system where the setup script is being run. They are simply downloaded to the ./.eggs directory if they’re not locally available already. If you want them to be installed, as well as being available when the setup script is run, you should add them to install_requires and setup_requires.)

dependency_links

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

namespace_packages

A list of strings naming the project’s “namespace packages”. A namespace package is a package that may be split across multiple project distributions. For example, Zope 3’s zope package is a namespace package, because subpackages like zope.interface and zope.publisher may be distributed separately. The egg runtime system can automatically merge such subpackages into a single parent package at runtime, as long as you declare them in each project that contains any subpackages of the namespace package, and as long as the namespace package’s __init__.py does not contain any code other than a namespace declaration. See the section below on Namespace Packages for more information.

test_suite

A string naming a unittest.TestCase subclass (or a package or module containing one or more of them, or a method of such a subclass), or naming a function that can be called with no arguments and returns a unittest.TestSuite. If the named suite is a module, and the module has an additional_tests() function, it is called and the results are added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite.

Specifying this argument enables use of the test command to run the specified test suite, e.g. via setup.py test. See the section on the test command below for more details.

New in 41.5.0: Deprecated the test command.

tests_require

If your project’s tests need one or more additional packages besides those needed to install it, you can use this option to specify them. It should be a string or list of strings specifying what other distributions need to be present for the package’s tests to run. When you run the test command, setuptools will attempt to obtain these (using pip if available). Note that these required projects will not be installed on the system where the tests are run, but only downloaded to the project’s setup directory if they’re not already installed locally.

New in 41.5.0: Deprecated the test command.

test_loader

If you would like to use a different way of finding tests to run than what setuptools normally uses, you can specify a module name and class name in this argument. The named class must be instantiable with no arguments, and its instances must support the loadTestsFromNames() method as defined in the Python unittest module’s TestLoader class. Setuptools will pass only one test “name” in the names argument: the value supplied for the test_suite argument. The loader you specify may interpret this string in any way it likes, as there are no restrictions on what may be contained in a test_suite string.

The module name and class name must be separated by a :. The default value of this argument is "setuptools.command.test:ScanningLoader". If you want to use the default unittest behavior, you can specify "unittest:TestLoader" as your test_loader argument instead. This will 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 the tests_require option to ensure that the package containing the loader class is available when the test command is run.

New in 41.5.0: Deprecated the test command.

eager_resources

A list of strings naming resources that should be extracted together, if any of them is needed, or if any C extensions included in the project are imported. This argument is only useful if the project will be installed as a zipfile, and there is a need to have all of the listed resources be extracted to the filesystem as a unit. Resources listed here should be “/”-separated paths, relative to the source root, so to list a resource foo.png in package bar.baz, you would include the string bar/baz/foo.png in this argument.

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

use_2to3

Convert the source code from Python 2 to Python 3 with 2to3 during the build process. See Supporting both Python 2 and Python 3 with Setuptools for more details.

convert_2to3_doctests

List of doctest source files that need to be converted with 2to3. See Supporting both Python 2 and Python 3 with Setuptools for more details.

use_2to3_fixers

A list of modules to search for additional fixers to be used during the 2to3 conversion. See Supporting both Python 2 and Python 3 with Setuptools for more details.

project_urls

An arbitrary map of URL names to hyperlinks, allowing more extensible documentation of where various resources can be found than the simple url and download_url options provide.

find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])

from setuptools import setup, find_namespace_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_namespace_packages(),
)

├── namespace
│   └── mypackage
│       ├── __init__.py
│       └── mod1.py
├── setup.py
└── tests
    └── test_mod1.py

from setuptools import setup, find_namespace_packages

setup(
    name="namespace.mypackage",
    version="0.1",
    packages=find_namespace_packages(include=["namespace.*"])
)

├── setup.py
├── src
│   └── namespace
│       └── mypackage
│           ├── __init__.py
│           └── mod1.py
└── tests
    └── test_mod1.py

setup(name="namespace.mypackage",
      version="0.1",
      package_dir={"": "src"},
      packages=find_namespace_packages(where="src"))

Automatic Script Creation

Packaging and installing scripts can be a bit awkward with the distutils. For one thing, there’s no easy way to have a script’s filename match local conventions on both Windows and POSIX platforms. For another, you often have to create a separate file just for the “main” script, when your actual “main” is a function in a module somewhere. And even in Python 2.4, using the -m option only works for actual .py files that aren’t installed in a package.

setuptools fixes all of these problems by automatically generating scripts for you with the correct extension, and on Windows it will even create an .exe file so that users don’t have to change their PATHEXT settings. The way to use this feature is to define “entry points” in your setup script that indicate what function the generated script should import and run. For example, to create two console scripts called foo and bar, and a GUI script called baz, you might do something like this:

setup(
    # other arguments here...
    entry_points={
        "console_scripts": [
            "foo = my_package.some_module:main_func",
            "bar = other_module:some_func",
        ],
        "gui_scripts": [
            "baz = my_package_gui:start_func",
        ]
    }
)

When this project is installed on non-Windows platforms (using “setup.py install”, “setup.py develop”, or with pip), a set of foo, bar, and baz scripts will be installed that import main_func and some_func from the specified modules. The functions you specify are called with no arguments, and their return value is passed to sys.exit(), so you can return an errorlevel or message to print to stderr.

On Windows, a set of foo.exe, bar.exe, and baz.exe launchers are created, alongside a set of foo.py, bar.py, and baz.pyw files. The .exe wrappers find and execute the right version of Python to run the .py or .pyw file.

You may define as many “console script” and “gui script” entry points as you like, and each one can optionally specify “extras” that it depends on, that will be added to sys.path when the script is run. For more information on “extras”, see the section below on Declaring Extras. For more information on “entry points” in general, see the section below on Dynamic Discovery of Services and Plugins.

setup(
    # other arguments here...
    entry_points={
        "setuptools.installation": [
            "eggsecutable = my_package.some_module:main_func",
        ]
    }
)

Declaring Dependencies

setuptools supports automatically installing dependencies when a package is installed, and including information about dependencies in Python Eggs (so that package management tools like pip can use the information).

setuptools and pkg_resources use a common syntax for specifying a project’s required dependencies. This syntax consists of a project’s PyPI name, optionally followed by a comma-separated list of “extras” in square brackets, optionally followed by a comma-separated list of version specifiers. A version specifier is one of the operators <, >, <=, >=, == or !=, followed by a version identifier. Tokens may be separated by whitespace, but any whitespace or nonstandard characters within a project name or version identifier must be replaced with -.

Version specifiers for a given project are internally sorted into ascending version order, and used to establish what ranges of versions are acceptable. Adjacent redundant conditions are also consolidated (e.g. ">1, >2" becomes ">2", and "<2,<3" becomes "<2"). "!=" versions are excised from the ranges they fall within. A project’s version is then checked for membership in the resulting ranges. (Note that providing conflicting conditions for the same version (e.g. “<2,>=2” or “==2,!=2”) is meaningless and may therefore produce bizarre results.)

Here are some example requirement specifiers:

docutils >= 0.3

# comment lines and \ continuations are allowed in requirement strings
BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
    ==1.6, ==1.7  # and so are line-end comments

PEAK[FastCGI, reST]>=0.5a4

setuptools==0.5a7

The simplest way to include requirement specifiers is to use the install_requires argument to setup(). It takes a string or list of strings containing requirement specifiers. If you include more than one requirement in a string, each requirement must begin on a new line.

This has three effects:

1. When your project is installed, either by using pip, setup.py install, or setup.py develop, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed.
2. Any scripts in your project will be installed with wrappers that verify the availability of the specified dependencies at runtime, and ensure that the correct versions are added to sys.path (e.g. if multiple versions have been installed).
3. Python Egg distributions will include a metadata file listing the dependencies.

Note, by the way, that if you declare your dependencies in setup.py, you do not need to use the require() function in your scripts or modules, as long as you either install the project or use setup.py develop to do development work on it. (See “Development Mode” below for more details on using setup.py develop.)

setup(
    ...
    dependency_links=[
        "http://peak.telecommunity.com/snapshots/"
    ],
)

setup(
    name="Project-A",
    ...
    extras_require={
        "PDF":  ["ReportLab>=1.2", "RXP"],
        "reST": ["docutils>=0.3"],
    }
)

setup(
    name="Project-A",
    ...
    entry_points={
        "console_scripts": [
            "rst2pdf = project_a.tools.pdfgen [PDF]",
            "rst2html = project_a.tools.htmlgen",
            # more script entry points ...
        ],
    }
)

setup(
    name="Project-B",
    install_requires=["Project-A[PDF]"],
    ...
)

setup(
    name="Project-A",
    ...
    extras_require={
        "PDF":  [],
        "reST": ["docutils>=0.3"],
    }
)

setup(
    name="Project",
    ...
    install_requires=[
        "enum34;python_version<'3.4'",
        "pywin32 >= 1.0;platform_system=='Windows'"
    ]
)

Including Data Files

The distutils have traditionally allowed installation of “data files”, which are placed in a platform-specific location. However, the most common use case for data files distributed with a package is for use by the package, usually by including the data files in the package directory.

Setuptools offers three ways to specify data files to be included in your packages. First, you can simply use the include_package_data keyword, e.g.:

from setuptools import setup, find_packages
setup(
    ...
    include_package_data=True
)

This tells setuptools to install any data files it finds in your packages. The data files must be specified via the distutils’ MANIFEST.in file. (They can also be tracked by a revision control system, using an appropriate plugin. See the section below on Adding Support for Revision Control Systems for information on how to write such plugins.)

If you want finer-grained control over what files are included (for example, if you have documentation files in your package directories and want to exclude them from installation), then you can also use the package_data keyword, e.g.:

from setuptools import setup, find_packages
setup(
    ...
    package_data={
        # If any package contains *.txt or *.rst files, include them:
        "": ["*.txt", "*.rst"],
        # And include any *.msg files found in the "hello" package, too:
        "hello": ["*.msg"],
    }
)

The package_data argument is a dictionary that maps from package names to lists of glob patterns. The globs may include subdirectory names, if the data files are contained in a subdirectory of the package. For example, if the package tree looks like this:

setup.py
src/
    mypkg/
        __init__.py
        mypkg.txt
        data/
            somefile.dat
            otherdata.dat

The setuptools setup file might look like this:

from setuptools import setup, find_packages
setup(
    ...
    packages=find_packages("src"),  # include all packages under src
    package_dir={"": "src"},   # tell distutils packages are under src

    package_data={
        # If any package contains *.txt files, include them:
        "": ["*.txt"],
        # And include any *.dat files found in the "data" subdirectory
        # of the "mypkg" package, also:
        "mypkg": ["data/*.dat"],
    }
)

Notice that if you list patterns in package_data under the empty string, these patterns are used to find files in every package, even ones that also have their own patterns listed. Thus, in the above example, the mypkg.txt file gets included even though it’s not listed in the patterns for mypkg.

Also notice that if you use paths, you must use a forward slash (/) as the path separator, even if you are on Windows. Setuptools automatically converts slashes to appropriate platform-specific separators at build time.

If datafiles are contained in a subdirectory of a package that isn’t a package itself (no __init__.py), then the subdirectory names (or *) are required in the package_data argument (as shown above with "data/*.dat").

When building an sdist, the datafiles are also drawn from the package_name.egg-info/SOURCES.txt file, so make sure that this is removed if the setup.py package_data list is updated before calling setup.py.

(Note: although the package_data argument was previously only available in setuptools, it was also added to the Python distutils package as of Python 2.4; there is some documentation for the feature available on the python.org website. If using the setuptools-specific include_package_data argument, files specified by package_data will not be automatically added to the manifest unless they are listed in the MANIFEST.in file.)

Sometimes, the include_package_data or package_data options alone aren’t sufficient to precisely define what files you want included. For example, you may want to include package README files in your revision control system and source distributions, but exclude them from being installed. So, setuptools offers an exclude_package_data option as well, that allows you to do things like this:

from setuptools import setup, find_packages
setup(
    ...
    packages=find_packages("src"),  # include all packages under src
    package_dir={"": "src"},   # tell distutils packages are under src

    include_package_data=True,    # include everything in source control

    # ...but exclude README.txt from all packages
    exclude_package_data={"": ["README.txt"]},
)

The exclude_package_data option is a dictionary mapping package names to lists of wildcard patterns, just like the package_data option. And, just as with that option, a key of "" will apply the given pattern(s) to all packages. However, any files that match these patterns will be excluded from installation, even if they were listed in package_data or were included as a result of using include_package_data.

In summary, the three options allow you to:

include_package_data

Accept all data files and directories matched by MANIFEST.in.

package_data

Specify additional patterns to match files that may or may not be matched by MANIFEST.in or found in source control.

exclude_package_data

Specify patterns for data files and directories that should not be included when a package is installed, even if they would otherwise have been included due to the use of the preceding options.

NOTE: Due to the way the distutils build process works, a data file that you include in your project and then stop including may be “orphaned” in your project’s build directories, requiring you to run setup.py clean --all to fully remove them. This may also be important for your users and contributors if they track intermediate revisions of your project using Subversion; be sure to let them know when you make changes that remove files from inclusion so they can run setup.py clean --all.

Extensible Applications and Frameworks

setup(
    # ...
    entry_points={"blogtool.parsers": ".rst = some_module:SomeClass"}
)

setup(
    # ...
    entry_points={"blogtool.parsers": [".rst = some_module:a_func"]}
)

setup(
    # ...
    entry_points="""
        [blogtool.parsers]
        .rst = some.nested.module:SomeClass.some_classmethod [reST]
    """,
    extras_require=dict(reST="Docutils>=0.3.5")
)

“Development Mode”

Under normal circumstances, the distutils assume that you are going to build a distribution of your project, not use it in its “raw” or “unbuilt” form. If you were to use the distutils that way, you would have to rebuild and reinstall your project every time you made a change to it during development.

Another problem that sometimes comes up with the distutils is that you may need to do development on two related projects at the same time. You may need to put both projects’ packages in the same directory to run them, but need to keep them separate for revision control purposes. How can you do this?

Setuptools allows you to deploy your projects for use in a common directory or staging area, but without copying any files. Thus, you can edit each project’s code in its checkout directory, and only need to run build commands when you change a project’s C extensions or similarly compiled files. You can even deploy a project into another project’s checkout directory, if that’s your preferred way of working (as opposed to using a common independent staging area or the site-packages directory).

To do this, use the setup.py develop command. It works very similarly to setup.py install, except that it doesn’t actually install anything. Instead, it creates a special .egg-link file in the deployment directory, that links to your project’s source code. And, if your deployment directory is Python’s site-packages directory, it will also update the easy-install.pth file to include your project’s source code, thereby making it available on sys.path for all programs using that Python installation.

If you have enabled the use_2to3 flag, then of course the .egg-link will not link directly to your source code when run under Python 3, since that source code would be made for Python 2 and not work under Python 3. Instead the setup.py develop will build Python 3 code under the build directory, and link there. This means that after doing code changes you will have to run setup.py build before these changes are picked up by your Python 3 installation.

In addition, the develop command creates wrapper scripts in the target script directory that will run your in-development scripts after ensuring that all your install_requires packages are available on sys.path.

You can deploy the same project to multiple staging areas, e.g. if you have multiple projects on the same machine that are sharing the same project you’re doing development work.

When you’re done with a given development task, you can remove the project source from a staging area using setup.py develop --uninstall, specifying the desired staging area if it’s not the default.

There are several options to control the precise behavior of the develop command; see the section on the develop command below for more details.

Note that you can also apply setuptools commands to non-setuptools projects, using commands like this:

python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop

That is, you can simply list the normal setup commands and options following the quoted part.

Distributing a setuptools-based project

Detailed instructions to distribute a setuptools project can be found at Packaging project tutorials.

Before you begin, make sure you have the latest versions of setuptools and wheel:

pip install --upgrade setuptools wheel

To build a setuptools project, run this command from the same directory where setup.py is located:

setup.py sdist bdist_wheel

This will generate distribution archives in the dist directory.

Before you upload the generated archives make sure you’re registered on https://test.pypi.org/account/register/. You will also need to verify your email to be able to upload any packages. You should install twine to be able to upload packages:

pip install --upgrade twine

Now, to upload these archives, run:

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

To install your newly uploaded package example_pkg, you can use pip:

pip install --index-url https://test.pypi.org/simple/ example_pkg

If you have issues at any point, please refer to Packaging project tutorials for clarification.

setup(
    # ...
    namespace_packages=["zope"]
)

__import__("pkg_resources").declare_namespace(__name__)

setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3

setup.py egg_info -Db "" sdist bdist_egg

setup.py alias -u release egg_info -Db ""

setup.py release sdist bdist_egg

[build-system]
requires=[..., "cython"]

[options]
setup_requires =
    ...
    cython

alias – Define shortcuts for commonly used commands

Sometimes, you need to use the same commands over and over, but you can’t necessarily set them as defaults. For example, if you produce both development snapshot releases and “stable” releases of a project, you may want to put the distributions in different places, or use different egg_info tagging options, etc. In these cases, it doesn’t make sense to set the options in a distutils configuration file, because the values of the options changed based on what you’re trying to do.

Setuptools therefore allows you to define “aliases” – shortcut names for an arbitrary string of commands and options, using setup.py alias aliasname expansion, where aliasname is the name of the new alias, and the remainder of the command line supplies its expansion. For example, this command defines a sitewide alias called “daily”, that sets various egg_info tagging options:

setup.py alias --global-config daily egg_info --tag-build=development

Once the alias is defined, it can then be used with other setup commands, e.g.:

setup.py daily bdist_egg        # generate a daily-build .egg file
setup.py daily sdist            # generate a daily-build source distro
setup.py daily sdist bdist_egg  # generate both

The above commands are interpreted as if the word daily were replaced with egg_info --tag-build=development.

Note that setuptools will expand each alias at most once in a given command line. This serves two purposes. First, if you accidentally create an alias loop, it will have no effect; you’ll instead get an error message about an unknown command. Second, it allows you to define an alias for a command, that uses that command. For example, this (project-local) alias:

setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg

redefines the bdist_egg command so that it always runs the rotate command afterwards to delete all but the newest egg file. It doesn’t loop indefinitely on bdist_egg because the alias is only expanded once when used.

You can remove a defined alias with the --remove (or -r) option, e.g.:

setup.py alias --global-config --remove daily

would delete the “daily” alias we defined above.

Aliases can be defined on a project-specific, per-user, or sitewide basis. The default is to define or remove a project-specific alias, but you can use any of the configuration file options (listed under the saveopts command, below) to determine which distutils configuration file an aliases will be added to (or removed from).

Note that if you omit the “expansion” argument to the alias command, you’ll get output showing that alias’ current definition (and what configuration file it’s defined in). If you omit the alias name as well, you’ll get a listing of all current aliases along with their configuration file locations.

bdist_egg – Create a Python Egg for the project

This command generates a Python Egg (.egg file) for the project. Python Eggs are the preferred binary distribution format for EasyInstall, because they are cross-platform (for “pure” packages), directly importable, and contain project metadata including scripts and information about the project’s dependencies. They can be simply downloaded and added to sys.path directly, or they can be placed in a directory on sys.path and then automatically discovered by the egg runtime system.

This command runs the egg_info command (if it hasn’t already run) to update the project’s metadata (.egg-info) directory. If you have added any extra metadata files to the .egg-info directory, those files will be included in the new egg file’s metadata directory, for use by the egg runtime system or by any applications or frameworks that use that metadata.

You won’t usually need to specify any special options for this command; just use bdist_egg and you’re done. But there are a few options that may be occasionally useful:

--dist-dir=DIR, -d DIR

Set the directory where the .egg file will be placed. If you don’t supply this, then the --dist-dir setting of the bdist command will be used, which is usually a directory named dist in the project directory.

--plat-name=PLATFORM, -p PLATFORM

Set the platform name string that will be embedded in the egg’s filename (assuming the egg contains C extensions). This can be used to override the distutils default platform name with something more meaningful. Keep in mind, however, that the egg runtime system expects to see eggs with distutils platform names, so it may ignore or reject eggs with non-standard platform names. Similarly, the EasyInstall program may ignore them when searching web pages for download links. However, if you are cross-compiling or doing some other unusual things, you might find a use for this option.

--exclude-source-files

Don’t include any modules’ .py files in the egg, just compiled Python, C, and data files. (Note that this doesn’t affect any .py files in the EGG-INFO directory or its subdirectories, since for example there may be scripts with a .py extension which must still be retained.) We don’t recommend that you use this option except for packages that are being bundled for proprietary end-user applications, or for “embedded” scenarios where space is at an absolute premium. On the other hand, if your package is going to be installed and used in compressed form, you might as well exclude the source because Python’s traceback module doesn’t currently understand how to display zipped source code anyway, or how to deal with files that are in a different place from where their code was compiled.

There are also some options you will probably never need, but which are there because they were copied from similar bdist commands used as an example for creating this one. They may be useful for testing and debugging, however, which is why we kept them:

--keep-temp, -k

Keep the contents of the --bdist-dir tree around after creating the .egg file.

--bdist-dir=DIR, -b DIR

Set the temporary directory for creating the distribution. The entire contents of this directory are zipped to create the .egg file, after running various installation commands to copy the package’s modules, data, and extensions here.

--skip-build

Skip doing any “build” commands; just go straight to the install-and-compress phases.

develop – Deploy the project source in “Development Mode”

This command allows you to deploy your project’s source for use in one or more “staging areas” where it will be available for importing. This deployment is done in such a way that changes to the project source are immediately available in the staging area(s), without needing to run a build or install step after each change.

The develop command works by creating an .egg-link file (named for the project) in the given staging area. If the staging area is Python’s site-packages directory, it also updates an easy-install.pth file so that the project is on sys.path by default for all programs run using that Python installation.

The develop command also installs wrapper scripts in the staging area (or a separate directory, as specified) that will ensure the project’s dependencies are available on sys.path before running the project’s source scripts. And, it ensures that any missing project dependencies are available in the staging area, by downloading and installing them if necessary.

Last, but not least, the develop command invokes the build_ext -i command to ensure any C extensions in the project have been built and are up-to-date, and the egg_info command to ensure the project’s metadata is updated (so that the runtime and wrappers know what the project’s dependencies are). If you make any changes to the project’s setup script or C extensions, you should rerun the develop command against all relevant staging areas to keep the project’s scripts, metadata and extensions up-to-date. Most other kinds of changes to your project should not require any build operations or rerunning develop, but keep in mind that even minor changes to the setup script (e.g. changing an entry point definition) require you to re-run the develop or test commands to keep the distribution updated.

Here are some of the options that the develop command accepts. Note that they affect the project’s dependencies as well as the project itself, so if you have dependencies that need to be installed and you use --exclude-scripts (for example), the dependencies’ scripts will not be installed either! For this reason, you may want to use pip to install the project’s dependencies before using the develop command, if you need finer control over the installation options for dependencies.

--uninstall, -u

Un-deploy the current project. You may use the --install-dir or -d option to designate the staging area. The created .egg-link file will be removed, if present and it is still pointing to the project directory. The project directory will be removed from easy-install.pth if the staging area is Python’s site-packages directory.

Note that this option currently does not uninstall script wrappers! You must uninstall them yourself, or overwrite them by using pip to install a different version of the package. You can also avoid installing script wrappers in the first place, if you use the --exclude-scripts (aka -x) option when you run develop to deploy the project.

--multi-version, -m

“Multi-version” mode. Specifying this option prevents develop from adding an easy-install.pth entry for the project(s) being deployed, and if an entry for any version of a project already exists, the entry will be removed upon successful deployment. In multi-version mode, no specific version of the package is available for importing, unless you use pkg_resources.require() to put it on sys.path, or you are running a wrapper script generated by setuptools. (In which case the wrapper script calls require() for you.)

Note that if you install to a directory other than site-packages, this option is automatically in effect, because .pth files can only be used in site-packages (at least in Python 2.3 and 2.4). So, if you use the --install-dir or -d option (or they are set via configuration file(s)) your project and its dependencies will be deployed in multi- version mode.

--install-dir=DIR, -d DIR

Set the installation directory (staging area). If this option is not directly specified on the command line or in a distutils configuration file, the distutils default installation location is used. Normally, this will be the site-packages directory, but if you are using distutils configuration files, setting things like prefix or install_lib, then those settings are taken into account when computing the default staging area.

--script-dir=DIR, -s DIR

Set the script installation directory. If you don’t supply this option (via the command line or a configuration file), but you have supplied an --install-dir (via command line or config file), then this option defaults to the same directory, so that the scripts will be able to find their associated package installation. Otherwise, this setting defaults to the location where the distutils would normally install scripts, taking any distutils configuration file settings into account.

--exclude-scripts, -x

Don’t deploy script wrappers. This is useful if you don’t want to disturb existing versions of the scripts in the staging area.

--always-copy, -a

Copy all needed distributions to the staging area, even if they are already present in another directory on sys.path. By default, if a requirement can be met using a distribution that is already available in a directory on sys.path, it will not be copied to the staging area.

--egg-path=DIR

Force the generated .egg-link file to use a specified relative path to the source directory. This can be useful in circumstances where your installation directory is being shared by code running under multiple platforms (e.g. Mac and Windows) which have different absolute locations for the code under development, but the same relative locations with respect to the installation directory. If you use this option when installing, you must supply the same relative path when uninstalling.

In addition to the above options, the develop command also accepts all of the same options accepted by easy_install. If you’ve configured any easy_install settings in your setup.cfg (or other distutils config files), the develop command will use them as defaults, unless you override them in a [develop] section or on the command line.

egg_info – Create egg metadata and set build tags

This command performs two operations: it updates a project’s .egg-info metadata directory (used by the bdist_egg, develop, and test commands), and it allows you to temporarily change a project’s version string, to support “daily builds” or “snapshot” releases. It is run automatically by the sdist, bdist_egg, develop, and test commands in order to update the project’s metadata, but you can also specify it explicitly in order to temporarily change the project’s version string while executing other commands. (It also generates the .egg-info/SOURCES.txt manifest file, which is used when you are building source distributions.)

In addition to writing the core egg metadata defined by setuptools and required by pkg_resources, this command can be extended to write other metadata files as well, by defining entry points in the egg_info.writers group. See the section on Adding new EGG-INFO Files below for more details. Note that using additional metadata writers may require you to include a setup_requires argument to setup() in order to ensure that the desired writers are available on sys.path.

setup.py egg_info --tag-date --tag-build=DEV bdist_egg

setup.py egg_info -RDb "" sdist bdist_egg

rotate – Delete outdated distribution files

As you develop new versions of your project, your distribution (dist) directory will gradually fill up with older source and/or binary distribution files. The rotate command lets you automatically clean these up, keeping only the N most-recently modified files matching a given pattern.

--match=PATTERNLIST, -m PATTERNLIST

Comma-separated list of glob patterns to match. This option is required. The project name and -* is prepended to the supplied patterns, in order to match only distributions belonging to the current project (in case you have a shared distribution directory for multiple projects). Typically, you will use a glob pattern like .zip or .egg to match files of the specified type. Note that each supplied pattern is treated as a distinct group of files for purposes of selecting files to delete.

--keep=COUNT, -k COUNT

Number of matching distributions to keep. For each group of files identified by a pattern specified with the --match option, delete all but the COUNT most-recently-modified files in that group. This option is required.

--dist-dir=DIR, -d DIR

Directory where the distributions are. This defaults to the value of the bdist command’s --dist-dir option, which will usually be the project’s dist subdirectory.

Example 1: Delete all .tar.gz files from the distribution directory, except for the 3 most recently modified ones:

setup.py rotate --match=.tar.gz --keep=3

Example 2: Delete all Python 2.3 or Python 2.4 eggs from the distribution directory, except the most recently modified one for each Python version:

setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1

saveopts – Save used options to a configuration file

Finding and editing distutils configuration files can be a pain, especially since you also have to translate the configuration options from command-line form to the proper configuration file format. You can avoid these hassles by using the saveopts command. Just add it to the command line to save the options you used. For example, this command builds the project using the mingw32 C compiler, then saves the –compiler setting as the default for future builds (even those run implicitly by the install command):

setup.py build --compiler=mingw32 saveopts

The saveopts command saves all options for every command specified on the command line to the project’s local setup.cfg file, unless you use one of the configuration file options to change where the options are saved. For example, this command does the same as above, but saves the compiler setting to the site-wide (global) distutils configuration:

setup.py build --compiler=mingw32 saveopts -g

Note that it doesn’t matter where you place the saveopts command on the command line; it will still save all the options specified for all commands. For example, this is another valid way to spell the last example:

setup.py saveopts -g build --compiler=mingw32

Note, however, that all of the commands specified are always run, regardless of where saveopts is placed on the command line.

setopt – Set a distutils or setuptools option in a config file

This command is mainly for use by scripts, but it can also be used as a quick and dirty way to change a distutils configuration option without having to remember what file the options are in and then open an editor.

Example 1. Set the default C compiler to mingw32 (using long option names):

setup.py setopt --command=build --option=compiler --set-value=mingw32

Example 2. Remove any setting for the distutils default package installation directory (short option names):

setup.py setopt -c install -o install_lib -r

Options for the setopt command:

--command=COMMAND, -c COMMAND

Command to set the option for. This option is required.

--option=OPTION, -o OPTION

The name of the option to set. This option is required.

--set-value=VALUE, -s VALUE

The value to set the option to. Not needed if -r or --remove is set.

--remove, -r

Remove (unset) the option, instead of setting it.

In addition to the above options, you may use any of the configuration file options (listed under the saveopts command, above) to determine which distutils configuration file the option will be added to (or removed from).

test – Build package and run a unittest suite

When doing test-driven development, or running automated builds that need testing before they are deployed for downloading or use, it’s often useful to be able to run a project’s unit tests without actually deploying the project anywhere, even using the develop command. The test command runs a project’s unit tests without actually deploying it, by temporarily putting the project’s source on sys.path, after first running build_ext -i and egg_info to ensure that any C extensions and project metadata are up-to-date.

To use this command, your project’s tests must be wrapped in a unittest test suite by either a function, a TestCase class or method, or a module or package containing TestCase classes. If the named suite is a module, and the module has an additional_tests() function, it is called and the result (which must be a unittest.TestSuite) is added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite. (Note: if your project specifies a test_loader, the rules for processing the chosen test_suite may differ; see the test_loader documentation for more details.)

Note that many test systems including doctest support wrapping their non-unittest tests in TestSuite objects. So, if you are using a test package that does not support this, we suggest you encourage its developers to implement test suite support, as this is a convenient and standard way to aggregate a collection of tests to be run under a common test harness.

By default, tests will be run in the “verbose” mode of the unittest package’s text test runner, but you can get the “quiet” mode (just dots) if you supply the -q or --quiet option, either as a global option to the setup script (e.g. setup.py -q test) or as an option for the test command itself (e.g. setup.py test -q). There is one other option available:

--test-suite=NAME, -s NAME

Specify the test suite (or module, class, or method) to be run (e.g. some_module.test_suite). The default for this option can be set by giving a test_suite argument to the setup() function, e.g.:

setup(
    # ...
    test_suite="my_package.tests.test_all"
)

If you did not set a test_suite in your setup() call, and do not provide a --test-suite option, an error will occur.

New in 41.5.0: Deprecated the test command.

upload – Upload source and/or egg distributions to PyPI

The upload command was deprecated in version 40.0 and removed in version 42.0. Use twine instead.

For more information on the current best practices in uploading your packages to PyPI, see the Python Packaging User Guide’s “Packaging Python Projects” tutorial specifically the section on uploading the distribution archives.

Using a src/ layout

One commonly used package configuration has all the module source code in a subdirectory (often called the src/ layout), like this:

├── src
│   └── mypackage
│       ├── __init__.py
│       └── mod1.py
├── setup.py
└── setup.cfg

You can set up your setup.cfg to automatically find all your packages in the subdirectory like this:

# This example contains just the necessary options for a src-layout, set up
# the rest of the file as described above.

[options]
package_dir=
    =src
packages=find:

[options.packages.find]
where=src

Specifying values

Some values are treated as simple strings, some allow more logic.

Type names used below:

• str – simple string
• list-comma – dangling list or string of comma-separated values
• list-semi – dangling list or string of semicolon-separated values
• bool – True is 1, yes, true
• dict – list-comma where keys are separated from values by =
• section – values are read from a dedicated (sub)section

Special directives:

• attr: – Value is read from a module attribute. attr: supports callables and iterables; unsupported types are cast using str().
• file: – Value is read from a list of files and then concatenated

Configuration API

Some automation tools may wish to access data from a configuration file.

Setuptools exposes a read_configuration() function for parsing metadata and options sections into a dictionary.

from setuptools.config import read_configuration

conf_dict = read_configuration("/home/user/dev/package/setup.cfg")

By default, read_configuration() will read only the file provided in the first argument. To include values from other configuration files which could be in various places, set the find_others keyword argument to True.

If you have only a configuration file but not the whole package, you can still try to get data out of it with the help of the ignore_option_errors keyword argument. When it is set to True, all options with errors possibly produced by directives, such as attr: and others, will be silently ignored. As a consequence, the resulting dictionary will include no such options.

Creating distutils Extensions

It can be hard to add new commands or setup arguments to the distutils. But the setuptools package makes it a bit easier, by allowing you to distribute a distutils extension as a separate project, and then have projects that need the extension just refer to it in their setup_requires argument.

With setuptools, your distutils extension projects can hook in new commands and setup() arguments just by defining “entry points”. These are mappings from command or argument names to a specification of where to import a handler from. (See the section on Dynamic Discovery of Services and Plugins above for some more background on entry points.)

setup(
    # ...
    entry_points={
        "distutils.commands": [
            "foo = mypackage.some_module:foo",
        ],
    },
)

setup(
    # ...
    entry_points={
        "distutils.commands": [
            "foo = mypackage.some_module:foo",
        ],
        "distutils.setup_keywords": [
            "bar_baz = mypackage.some_module:validate_bar_baz",
        ],
    },
)

def assert_bool(dist, attr, value):
    """Verify that value is True, False, 0, or 1"""
    if bool(value) != value:
        raise DistutilsSetupError(
            "%r must be a boolean value (got %r)" % (attr,value)
        )

setup(
    # ...
    entry_points={
        "distutils.setup_keywords": [
            "foo_bar = setuptools.dist:assert_string_list",
        ],
        "egg_info.writers": [
            "foo_bar.txt = setuptools.command.egg_info:write_arg",
        ],
    },
)

def write_arg(cmd, basename, filename):
    argname = os.path.splitext(basename)[0]
    value = getattr(cmd.distribution, argname, None)
    if value is not None:
        value = "\n".join(value) + "\n"
    cmd.write_or_delete_file(argname, filename, value)

def find_files_for_foobar(dirname):
    # loop to yield paths that start with `dirname`

entry_points={
    "setuptools.file_finders": [
        "foobar = my_foobar_module:find_files_for_foobar",
    ]
}

Mailing List and Bug Tracker

Please use the distutils-sig mailing list for questions and discussion about setuptools, and the setuptools bug tracker ONLY for issues you have confirmed via the list are actual bugs, and which you have reduced to a minimal set of steps to reproduce.