Installing setuptools

Windows users can just download and run the setuptools binary installer for Windows. All others should just download ez_setup.py and run it; this will download and install the appropriate egg for your Python version.

You may receive a message telling you about an obsolete version of setuptools being present; if so, you must be sure to delete it entirely, along with the old pkg_resources module if it's present on sys.path.

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. Just by doing the above, this project will be able to produce eggs, upload to PyPI, and automatically include all packages in the directory where the setup.py lives. See the sections below on Enhanced Commands and New Commands to see what commands you can give to this setup.py.

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 for upload to PyPI
    author = "Me",
    author_email = "me@example.com",
    description = "This is an Example Package",
    license = "PSF",
    keywords = "hello world example examples",
    url = "http://example.com/HelloWorld/",   # project home page, if any

    # could also include long_description, download_url, classifiers, etc.
)

In the following sections, we'll explain what most of these

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 EasyInstall 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 -.

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 EasyInstall, 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(
    name="Project-A",
    ...
    extras_require = {
        'PDF':  ["ReportLab>=1.2", "RXP"],
        'reST': ["docutils>=0.3"],
    }
)

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

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

Distributing a setuptools-based package

Your users might not have setuptools installed on their machines, or even if they do, it might not be the right version. Fixing this is easy; just download ez_setup.py, and put it in the same directory as your setup.py script. (Be sure to add it to your revision control system, too.) Then add these two lines to the very top of your setup script, before the script imports anything from setuptools:

import ez_setup
ez_setup.use_setuptools()

That's it. The ez_setup module will automatically download a matching version of setuptools from PyPI, if it isn't present on the target system. Whenever you install an updated version of setuptools, you should also update your projects' ez_setup.py files, so that a matching version gets installed on the target machine(s). If you're using Subversion, you may wish to use "externals" to make all your projects share a single ez_setup.py, so that you only have to update it in one place to update all your projects.

By the way, setuptools supports the new PyPI "upload" command, so you can use setup.py sdist upload or setup.py bdist_egg upload to upload your source or egg distributions respectively. Your project's current version must be registered with PyPI first, of course; you can use setup.py register to do that. Or you can do it all in one step, e.g. setup.py register sdist bdist_egg upload will register the package, build source and egg distributions, and then upload them both to PyPI, where they'll be easily found by other projects that depend on them.

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 supports this by allowing a package_data argument to setup(), 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.

(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.)

"Development Mode"

Sorry, this section isn't written yet, and neither is anything below this point except the changelog. You might want to subscribe to changes in this page to see when the documentation is added or updated.

Using find_packages()

XXX

Building Extensions written with Pyrex

XXX

build_ext - automatic support for Pyrex extensions

XXX

bdist, sdist - added support for "daily" or "special" build tagging

XXX

sdist - auto-include files from CVS or Subversion

XXX

upload - support uploading Python Eggs

XXX

alias - Define shortcuts for commonly used commands

XXX

bdist_egg - Create a Python Egg for the package

XXX

develop - "Install" the source package in-place

XXX

egg_info - Create egg metadata and set build tags

XXX

easy_install - Find, download, and install other packages

XXX

test - Build package and run a unittest suite

XXX

rotate - Delete outdated distribution files

XXX

saveopts - Save used options to a configuration file

XXX

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

XXX

Subclassing Command

XXX

Utility Modules