Generated
2014-09-04 21:09:36
Python version
3.3.2 (v3.3.2:d047928ae3f6, May 16 2013, 00:03:43) [MSC v.1600 32 bit (Intel)]
distutils version
3.3.2
setuptools version
1.1.7

Contents

Overview

This page assembles documentation for Python's distutils and setuptools libraries, particularly the setup() function. Most of the data on this page has been assembled automatically from distutils and setuptools source code.

Customary use case

Distutils and Setuptools are each intended to be used by calling distutils.core.setup() from a command-line script setup.py. (See sketch: TODO)
Consequently the user will be interested in:
  • Command-line arguments interpreted by setup( ), and treated as a sequence of distutils or setuptools "commands" with "arguments".
  • Arguments allowed to the setup() function itself
  • Applicable configuration files

Command-line invocation of setup.py

Usage as documented by distutils.core.USAGE:

  • setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
  • setup.py --help [cmd1 cmd2 ...]
  • setup.py --help-commands
  • setup.py cmd --help

Usage as documented by Distribution.common_usage:

Common commands: (see '--help-commands' for more)
Example invocation
Description
setup.py build
will build the package underneath 'build/'
setup.py install
will install the package

Command line parsing details

Command line parsing details from parse_command_line( ) functions' doc strings:
distutils
Parse the setup script's command line, taken from the 'script_args' instance attribute (which defaults to 'sys.argv[1:]' -- see 'setup()' in core.py). This list is first processed for "global options" -- options that set attributes of the Distribution instance. Then, it is alternately scanned for Distutils commands and options for that command. Each new command terminates the options for the previous command. The allowed options for a command are determined by the 'user_options' attribute of the command class -- thus, we have to be able to load command classes in order to parse the command line. Any error in that 'options' attribute raises DistutilsGetoptError; any error on the command-line raises DistutilsArgError. If no Distutils commands were found on the command line, raises DistutilsArgError. Return true if command-line was successfully parsed and we should carry on with executing commands; false if no errors but we shouldn't execute commands (currently, this only happens if user asks for help).
setuptools
Process features after parsing command line options

setup.py commands summary

Command-line options that distutils.core.setup( ) interprets as commands.
Command
DU
ST
Description
build
DU
du
build everything needed to install
build_py
DU
ST
"build" pure Python modules (copy to build directory)
build_ext
DU
ST
build C/C++ extensions (compile/link to build directory)
build_clib
DU
du
build C/C++ libraries used by Python extensions
build_scripts
DU
du
"build" scripts (copy and fixup #! line)
clean
DU
du
clean up temporary files from 'build' command
install
DU
ST
install everything from build directory
install_lib
DU
ST
install all Python modules (extensions and pure Python)
install_headers
DU
du
install C/C++ header files
install_scripts
DU
ST
install scripts (Python or otherwise)
install_data
DU
du
install data files
sdist
DU
ST
create a source distribution (tarball, zip file, etc.)
register
DU
ST
register the distribution with the Python package index
bdist
DU
du
create a built (binary) distribution
bdist_dumb
DU
du
create a "dumb" built distribution
bdist_rpm
DU
ST
create an RPM distribution
bdist_wininst
DU
ST
create an executable installer for MS Windows
check
DU
du
perform some checks on the package
upload
DU
du
upload binary package to PyPI
alias

ST
define a shortcut to invoke one or more commands
bdist_egg

ST
create an "egg" distribution
develop

ST
install package in 'development mode'
easy_install

ST
Find/get/install Python packages
egg_info

ST
create a distribution's .egg-info directory
rotate

ST
delete older distributions, keeping N newest files
saveopts

ST
save supplied options to setup.cfg or other config file
setopt

ST
set an option in setup.cfg or another config file
test

ST
run unit tests after in-place build
install_egg_info

ST
Install an .egg-info directory for the package
upload_docs

ST
Upload documentation to PyPI

General options

Global and Display options to setup.py, which must be provided on the command line before Commands.

Global options

Long
Short
Args
Description
--verbose
-v

run verbosely (default)
--quiet
-q

run quietly (turns verbosity off)
--dry-run
-n

don't actually do anything
--help
-h

show detailed help message
--command-packages

arg
list of packages that provide distutils commands

Display options

Long
Short
Args
Description
--help-commands


list all available commands
--name


print package name
--version
-V

print package version
--fullname


print <package name>-<version>
--author


print the author's name
--author-email


print the author's email address
--maintainer


print the maintainer's name
--maintainer-email


print the maintainer's email address
--contact


print the maintainer's name if known, else the author's
--contact-email


print the maintainer's email address if known, else the author's
--url


print the URL for this package
--license


print the license of the package
--licence


alias for --license
--description


print the package description
--long-description


print the long package description
--platforms


print the list of platforms
--classifiers


print the list of classifiers
--keywords


print the list of keywords
--provides


print the list of packages/modules provided
--requires


print the list of packages/modules required
--obsoletes


print the list of packages/modules made obsolete

Command Details

Commands listed in alphabetical order.

Command: alias


distutils
setuptools
Command defined in

ST
Description

define a shortcut to invoke one or more commands
Doc string

Define a shortcut that invokes one or more commands

Options for alias

Long
Short
Args
bool
DU
ST
Description
--remove
-r

bool

ST
remove (unset) the alias
--global-config
-g

bool

ST
save options to the site-wide distutils.cfg file
--user-config
-u

bool

ST
save options to the current user's pydistutils.cfg file
--filename
-f
arg


ST
configuration file to use (default=setup.cfg)

Command: bdist


distutils
setuptools
Command defined in
DU
du
Description
create a built (binary) distribution

Doc string
[None]

Options for bdist

Long
Short
Args
bool
DU
ST
Description
--bdist-base
-b
arg

DU
du
temporary directory for creating built distributions
--plat-name
-p
arg

DU
du
platform name to embed in generated filenames (default: win32)
--formats

arg

DU
du
formats for distribution (comma-separated list)
--dist-dir
-d
arg

DU
du
directory to put final built distributions in [default: dist]
--skip-build


bool
DU
du
skip rebuilding everything (for testing/debugging)
--help-formats



DU
du
lists available distribution formats

Command: bdist_dumb


distutils
setuptools
Command defined in
DU
du
Description
create a "dumb" built distribution

Doc string
[None]

Options for bdist_dumb

Long
Short
Args
bool
DU
ST
Description
--bdist-dir
-d
arg

DU
du
temporary directory for creating the distribution
--plat-name
-p
arg

DU
du
platform name to embed in generated filenames (default: win32)
--format
-f
arg

DU
du
archive format to create (tar, ztar, gztar, zip)
--keep-temp
-k

bool
DU
du
keep the pseudo-installation tree around after creating the distribution archive
--dist-dir
-d
arg

DU
du
directory to put final built distributions in
--skip-build


bool
DU
du
skip rebuilding everything (for testing/debugging)
--relative


bool
DU
du
build the archive using relative paths(default: false)

Command: bdist_egg


distutils
setuptools
Command defined in

ST
Description

create an "egg" distribution
Doc string

[None]

Options for bdist_egg

Long
Short
Args
bool
DU
ST
Description
--bdist-dir
-b
arg


ST
temporary directory for creating the distribution
--plat-name
-p
arg


ST
platform name to embed in generated filenames (default: win32)
--exclude-source-files


bool

ST
remove all .py files from the generated egg
--keep-temp
-k

bool

ST
keep the pseudo-installation tree around after creating the distribution archive
--dist-dir
-d
arg


ST
directory to put final built distributions in
--skip-build


bool

ST
skip rebuilding everything (for testing/debugging)

Command: bdist_rpm


distutils
setuptools
Command defined in
DU
ST
Description
create an RPM distribution
create an RPM distribution
Doc string
[None]
[None]

Options for bdist_rpm

Long
Short
Args
bool
DU
ST
Description
--bdist-base

arg

DU
ST
base directory for creating built distributions
--rpm-base

arg

DU
ST
base directory for creating RPMs (defaults to "rpm" under --bdist-base; must be specified for RPM 2)
--dist-dir
-d
arg

DU
ST
directory to put final RPM files in (and .spec files if --spec-only)
--python

arg

DU
ST
path to Python interpreter to hard-code in the .spec file (default: "python")
--fix-python



DU
ST
hard-code the exact path to the current Python interpreter in the .spec file
--spec-only



DU
ST
only regenerate spec file
--source-only



DU
ST
only generate source RPM
--binary-only



DU
ST
only generate binary RPM
--use-bzip2



DU
ST
use bzip2 instead of gzip to create source distribution
--distribution-name

arg

DU
ST
name of the (Linux) distribution to which this RPM applies (*not* the name of the module distribution!)
--group

arg

DU
ST
package classification [default: "Development/Libraries"]
--release

arg

DU
ST
RPM release number
--serial

arg

DU
ST
RPM serial number
--vendor

arg

DU
ST
RPM "vendor" (eg. "Joe Blow <joe@example.com>") [default: maintainer or author from setup script]
--packager

arg

DU
ST
RPM packager (eg. "Jane Doe <jane@example.net>")[default: vendor]
--doc-files

arg

DU
ST
list of documentation files (space or comma-separated)
--changelog

arg

DU
ST
RPM changelog
--icon

arg

DU
ST
name of icon file
--provides

arg

DU
ST
capabilities provided by this package
--requires

arg

DU
ST
capabilities required by this package
--conflicts

arg

DU
ST
capabilities which conflict with this package
--build-requires

arg

DU
ST
capabilities required to build this package
--obsoletes

arg

DU
ST
capabilities made obsolete by this package
--no-autoreq


bool
DU
ST
do not automatically calculate dependencies
--keep-temp
-k

bool
DU
ST
don't clean up RPM build directory
--no-keep-temp



DU
ST
clean up RPM build directory [default]
--use-rpm-opt-flags


bool
DU
ST
compile with RPM_OPT_FLAGS when building from source RPM
--no-rpm-opt-flags



DU
ST
do not pass any RPM CFLAGS to compiler
--rpm3-mode


bool
DU
ST
RPM 3 compatibility mode (default)
--rpm2-mode



DU
ST
RPM 2 compatibility mode
--prep-script

arg

DU
ST
Specify a script for the PREP phase of RPM building
--build-script

arg

DU
ST
Specify a script for the BUILD phase of RPM building
--pre-install

arg

DU
ST
Specify a script for the pre-INSTALL phase of RPM building
--install-script

arg

DU
ST
Specify a script for the INSTALL phase of RPM building
--post-install

arg

DU
ST
Specify a script for the post-INSTALL phase of RPM building
--pre-uninstall

arg

DU
ST
Specify a script for the pre-UNINSTALL phase of RPM building
--post-uninstall

arg

DU
ST
Specify a script for the post-UNINSTALL phase of RPM building
--clean-script

arg

DU
ST
Specify a script for the CLEAN phase of RPM building
--verify-script

arg

DU
ST
Specify a script for the VERIFY phase of the RPM build
--force-arch

arg

DU
ST
Force an architecture onto the RPM build process
--quiet
-q

bool
DU
ST
Run the INSTALL phase of RPM building in quiet mode

Command: bdist_wininst


distutils
setuptools
Command defined in
DU
ST
Description
create an executable installer for MS Windows
create an executable installer for MS Windows
Doc string
[None]
[None]

Options for bdist_wininst

Long
Short
Args
bool
DU
ST
Description
--bdist-dir

arg

DU
ST
temporary directory for creating the distribution
--plat-name
-p
arg

DU
ST
platform name to embed in generated filenames (default: win32)
--keep-temp
-k

bool
DU
ST
keep the pseudo-installation tree around after creating the distribution archive
--target-version

arg

DU
ST
require a specific python version on the target system
--no-target-compile
-c

bool
DU
ST
do not compile .py to .pyc on the target system
--no-target-optimize
-o

bool
DU
ST
do not compile .py to .pyo (optimized)on the target system
--dist-dir
-d
arg

DU
ST
directory to put final built distributions in
--bitmap
-b
arg

DU
ST
bitmap to use for the installer instead of python-powered logo
--title
-t
arg

DU
ST
title to display on the installer background instead of default
--skip-build


bool
DU
ST
skip rebuilding everything (for testing/debugging)
--install-script

arg

DU
ST
basename of installation script to be run afterinstallation or before deinstallation
--pre-install-script

arg

DU
ST
Fully qualified filename of a script to be run before any files are installed. This script need not be in the distribution
--user-access-control

arg

DU
ST
specify Vista's UAC handling - 'none'/default=no handling, 'auto'=use UAC if target Python installed for all users, 'force'=always use UAC

Command: build


distutils
setuptools
Command defined in
DU
du
Description
build everything needed to install

Doc string
[None]

Options for build

Long
Short
Args
bool
DU
ST
Description
--build-base
-b
arg

DU
du
base directory for build library
--build-purelib

arg

DU
du
build directory for platform-neutral distributions
--build-platlib

arg

DU
du
build directory for platform-specific distributions
--build-lib

arg

DU
du
build directory for all distribution (defaults to either build-purelib or build-platlib
--build-scripts

arg

DU
du
build directory for scripts
--build-temp
-t
arg

DU
du
temporary build directory
--plat-name
-p
arg

DU
du
platform name to build for, if supported (default: win32)
--compiler
-c
arg

DU
du
specify the compiler type
--debug
-g

bool
DU
du
compile extensions and libraries with debugging information
--force
-f

bool
DU
du
forcibly build everything (ignore file timestamps)
--executable
-e
arg

DU
du
specify final destination interpreter path (build.py)
--help-compiler



DU
du
list available compilers

Command: build_clib


distutils
setuptools
Command defined in
DU
du
Description
build C/C++ libraries used by Python extensions

Doc string
[None]

Options for build_clib

Long
Short
Args
bool
DU
ST
Description
--build-clib
-b
arg

DU
du
directory to build C/C++ libraries to
--build-temp
-t
arg

DU
du
directory to put temporary build by-products
--debug
-g

bool
DU
du
compile with debugging information
--force
-f

bool
DU
du
forcibly build everything (ignore file timestamps)
--compiler
-c
arg

DU
du
specify the compiler type
--help-compiler



DU
du
list available compilers

Command: build_ext


distutils
setuptools
Command defined in
DU
ST
Description
build C/C++ extensions (compile/link to build directory)
build C/C++ extensions (compile/link to build directory)
Doc string
[None]
[None]

Options for build_ext

Long
Short
Args
bool
DU
ST
Description
--build-lib
-b
arg

DU
ST
directory for compiled extension modules
--build-temp
-t
arg

DU
ST
directory for temporary files (build by-products)
--plat-name
-p
arg

DU
ST
platform name to cross-compile for, if supported (default: win32)
--inplace
-i

bool
DU
ST
ignore build-lib and put compiled extensions into the source directory alongside your pure Python modules
--include-dirs
-I
arg

DU
ST
list of directories to search for header files (separated by ';')
--define
-D
arg

DU
ST
C preprocessor macros to define
--undef
-U
arg

DU
ST
C preprocessor macros to undefine
--libraries
-l
arg

DU
ST
external C libraries to link with
--library-dirs
-L
arg

DU
ST
directories to search for external C libraries (separated by ';')
--rpath
-R
arg

DU
ST
directories to search for shared C libraries at runtime
--link-objects
-O
arg

DU
ST
extra explicit link objects to include in the link
--debug
-g

bool
DU
ST
compile/link with debugging information
--force
-f

bool
DU
ST
forcibly build everything (ignore file timestamps)
--compiler
-c
arg

DU
ST
specify the compiler type
--swig-cpp


bool
DU
ST
make SWIG create C++ files (default is C)
--swig-opts

arg

DU
ST
list of SWIG command line options
--swig

arg

DU
ST
path to the SWIG executable
--user


bool
DU
ST
add user include, library and rpath
--help-compiler



DU
ST
list available compilers

Command: build_py


distutils
setuptools
Command defined in
DU
ST
Description
"build" pure Python modules (copy to build directory)
"build" pure Python modules (copy to build directory)
Doc string
[None]
Enhanced 'build_py' command that includes data files with packages
The data files are specified via a 'package_data' argument to 'setup()'. See 'setuptools.dist.Distribution' for more details.
Also, this version of the 'build_py' command allows you to specify both 'py_modules' and 'packages' in the same setup operation.

Options for build_py

Long
Short
Args
bool
DU
ST
Description
--build-lib
-d
arg

DU
ST
directory to "build" (copy) to
--compile
-c

bool
DU
ST
compile .py to .pyc
--no-compile



DU
ST
don't compile .py files [default]
--optimize
-O
arg

DU
ST
also compile with optimization: -O1 for "python -O", -O2 for "python -OO", and -O0 to disable [default: -O0]
--force
-f

bool
DU
ST
forcibly build everything (ignore file timestamps)

Command: build_scripts


distutils
setuptools
Command defined in
DU
du
Description
"build" scripts (copy and fixup #! line)

Doc string
[None]

Options for build_scripts

Long
Short
Args
bool
DU
ST
Description
--build-dir
-d
arg

DU
du
directory to "build" (copy) to
--force
-f

bool
DU
du
forcibly build everything (ignore file timestamps
--executable
-e
arg

DU
du
specify final destination interpreter path

Command: check


distutils
setuptools
Command defined in
DU
du
Description
perform some checks on the package

Doc string
This command checks the meta-data of the package.

Options for check

Long
Short
Args
bool
DU
ST
Description
--metadata
-m

bool
DU
du
Verify meta-data
--restructuredtext
-r

bool
DU
du
Checks if long string meta-data syntax are reStructuredText-compliant
--strict
-s

bool
DU
du
Will exit with an error if a check fails

Command: clean


distutils
setuptools
Command defined in
DU
du
Description
clean up temporary files from 'build' command

Doc string
[None]

Options for clean

Long
Short
Args
bool
DU
ST
Description
--build-base
-b
arg

DU
du
base build directory (default: 'build.build-base')
--build-lib

arg

DU
du
build directory for all modules (default: 'build.build-lib')
--build-temp
-t
arg

DU
du
temporary build directory (default: 'build.build-temp')
--build-scripts

arg

DU
du
build directory for scripts (default: 'build.build-scripts')
--bdist-base

arg

DU
du
temporary directory for built distributions
--all
-a

bool
DU
du
remove all build output, not just temporary by-products

Command: develop


distutils
setuptools
Command defined in

ST
Description

install package in 'development mode'
Doc string

Set up package for development

Options for develop

Long
Short
Args
bool
DU
ST
Description
--prefix

arg


ST
installation prefix
--zip-ok
-z

bool

ST
install package as a zipfile
--multi-version
-m

bool

ST
make apps have to require() a version
--upgrade
-U

bool

ST
force upgrade (searches PyPI for latest versions)
--install-dir
-d
arg


ST
install package to DIR
--script-dir
-s
arg


ST
install scripts to DIR
--exclude-scripts
-x

bool

ST
Don't install scripts
--always-copy
-a

bool

ST
Copy all needed packages to install dir
--index-url
-i
arg


ST
base URL of Python Package Index
--find-links
-f
arg


ST
additional URL(s) to search for packages
--build-directory
-b
arg


ST
download/extract/build in DIR; keep the results
--optimize
-O
arg


ST
also compile with optimization: -O1 for "python -O", -O2 for "python -OO", and -O0 to disable [default: -O0]
--record

arg


ST
filename in which to record list of installed files
--always-unzip
-Z



ST
don't install as a zipfile, no matter what
--site-dirs
-S
arg


ST
list of directories where .pth files work
--editable
-e

bool

ST
Install specified packages in editable form
--no-deps
-N

bool

ST
don't install dependencies
--allow-hosts
-H
arg


ST
pattern(s) that hostnames must match
--local-snapshots-ok
-l

bool

ST
allow building eggs from local checkouts
--version


bool

ST
print version information and exit
--no-find-links




ST
Don't load find-links defined in packages being installed
--uninstall
-u

bool

ST
Uninstall this source package
--egg-path

arg


ST
Set the path to be used in the .egg-link file

Command: easy_install


distutils
setuptools
Command defined in

ST
Description

Find/get/install Python packages
Doc string

Manage a download/build/install process

Options for easy_install

Long
Short
Args
bool
DU
ST
Description
--prefix

arg


ST
installation prefix
--zip-ok
-z

bool

ST
install package as a zipfile
--multi-version
-m

bool

ST
make apps have to require() a version
--upgrade
-U

bool

ST
force upgrade (searches PyPI for latest versions)
--install-dir
-d
arg


ST
install package to DIR
--script-dir
-s
arg


ST
install scripts to DIR
--exclude-scripts
-x

bool

ST
Don't install scripts
--always-copy
-a

bool

ST
Copy all needed packages to install dir
--index-url
-i
arg


ST
base URL of Python Package Index
--find-links
-f
arg


ST
additional URL(s) to search for packages
--build-directory
-b
arg


ST
download/extract/build in DIR; keep the results
--optimize
-O
arg


ST
also compile with optimization: -O1 for "python -O", -O2 for "python -OO", and -O0 to disable [default: -O0]
--record

arg


ST
filename in which to record list of installed files
--always-unzip
-Z



ST
don't install as a zipfile, no matter what
--site-dirs
-S
arg


ST
list of directories where .pth files work
--editable
-e

bool

ST
Install specified packages in editable form
--no-deps
-N

bool

ST
don't install dependencies
--allow-hosts
-H
arg


ST
pattern(s) that hostnames must match
--local-snapshots-ok
-l

bool

ST
allow building eggs from local checkouts
--version


bool

ST
print version information and exit
--no-find-links




ST
Don't load find-links defined in packages being installed

Command: egg_info


distutils
setuptools
Command defined in

ST
Description

create a distribution's .egg-info directory
Doc string

[None]

Options for egg_info

Long
Short
Args
bool
DU
ST
Description
--egg-base
-e
arg


ST
directory containing .egg-info directories (default: top of the source tree)
--tag-svn-revision
-r

bool

ST
Add subversion revision ID to version number
--tag-date
-d

bool

ST
Add date stamp (e.g. 20050528) to version number
--tag-build
-b
arg


ST
Specify explicit tag to add to version number
--no-svn-revision
-R



ST
Don't add subversion revision ID [default]
--no-date
-D



ST
Don't include date stamp [default]

Command: install


distutils
setuptools
Command defined in
DU
ST
Description
install everything from build directory
install everything from build directory
Doc string
[None]
Use easy_install to install the package, w/dependencies

Options for install

Long
Short
Args
bool
DU
ST
Description
--prefix

arg

DU
ST
installation prefix
--exec-prefix

arg

DU
ST
(Unix only) prefix for platform-specific files
--home

arg

DU
ST
(Unix only) home directory to install under
--install-base

arg

DU
ST
base installation directory (instead of --prefix or --home)
--install-platbase

arg

DU
ST
base installation directory for platform-specific files (instead of --exec-prefix or --home)
--root

arg

DU
ST
install everything relative to this alternate root directory
--install-purelib

arg

DU
ST
installation directory for pure Python module distributions
--install-platlib

arg

DU
ST
installation directory for non-pure module distributions
--install-lib

arg

DU
ST
installation directory for all module distributions (overrides --install-purelib and --install-platlib)
--install-headers

arg

DU
ST
installation directory for C/C++ headers
--install-scripts

arg

DU
ST
installation directory for Python scripts
--install-data

arg

DU
ST
installation directory for data files
--compile
-c

bool
DU
ST
compile .py to .pyc [default]
--no-compile



DU
ST
don't compile .py files
--optimize
-O
arg

DU
ST
also compile with optimization: -O1 for "python -O", -O2 for "python -OO", and -O0 to disable [default: -O0]
--force
-f

bool
DU
ST
force installation (overwrite any existing files)
--skip-build


bool
DU
ST
skip rebuilding everything (for testing/debugging)
--record

arg

DU
ST
filename in which to record list of installed files
--user


bool
DU
ST
install in user site-package 'C:\Users\graham\AppData\Roaming\Python\Python33\site-packages'
--old-and-unmanageable


bool

ST
Try not to use this!
--single-version-externally-managed


bool

ST
used by system package builders to create 'flat' eggs

Command: install_data


distutils
setuptools
Command defined in
DU
du
Description
install data files

Doc string
[None]

Options for install_data

Long
Short
Args
bool
DU
ST
Description
--install-dir
-d
arg

DU
du
base directory for installing data files (default: installation base dir)
--root

arg

DU
du
install everything relative to this alternate root directory
--force
-f

bool
DU
du
force installation (overwrite existing files)

Command: install_egg_info


distutils
setuptools
Command defined in

ST
Description

Install an .egg-info directory for the package
Doc string

Install an .egg-info directory for the package

Options for install_egg_info

Long
Short
Args
bool
DU
ST
Description
--install-dir
-d
arg


ST
directory to install to

Command: install_headers


distutils
setuptools
Command defined in
DU
du
Description
install C/C++ header files

Doc string
[None]

Options for install_headers

Long
Short
Args
bool
DU
ST
Description
--install-dir
-d
arg

DU
du
directory to install header files to
--force
-f

bool
DU
du
force installation (overwrite existing files)

Command: install_lib


distutils
setuptools
Command defined in
DU
ST
Description
install all Python modules (extensions and pure Python)
install all Python modules (extensions and pure Python)
Doc string
[None]
Don't add compiled flags to filenames of non-Python files

Options for install_lib

Long
Short
Args
bool
DU
ST
Description
--install-dir
-d
arg

DU
ST
directory to install to
--build-dir
-b
arg

DU
ST
build directory (where to install from)
--force
-f

bool
DU
ST
force installation (overwrite existing files)
--compile
-c

bool
DU
ST
compile .py to .pyc [default]
--no-compile



DU
ST
don't compile .py files
--optimize
-O
arg

DU
ST
also compile with optimization: -O1 for "python -O", -O2 for "python -OO", and -O0 to disable [default: -O0]
--skip-build


bool
DU
ST
skip the build steps

Command: install_scripts


distutils
setuptools
Command defined in
DU
ST
Description
install scripts (Python or otherwise)
install scripts (Python or otherwise)
Doc string
[None]
Do normal script install, plus any egg_info wrapper scripts

Options for install_scripts

Long
Short
Args
bool
DU
ST
Description
--install-dir
-d
arg

DU
ST
directory to install scripts to
--build-dir
-b
arg

DU
ST
build directory (where to install from)
--force
-f

bool
DU
ST
force installation (overwrite existing files)
--skip-build


bool
DU
ST
skip the build steps

Command: register


distutils
setuptools
Command defined in
DU
ST
Description
register the distribution with the Python package index
register the distribution with the Python package index
Doc string
[None]
[None]

Options for register

Long
Short
Args
bool
DU
ST
Description
--repository
-r
arg

DU
ST
url of repository [default: http://pypi.python.org/pypi]
--show-response


bool
DU
ST
display full response text from server
--list-classifiers


bool
DU
ST
list the valid Trove classifiers
--strict


bool
DU
ST
Will stop the registering if the meta-data are not fully compliant

Command: rotate


distutils
setuptools
Command defined in

ST
Description

delete older distributions, keeping N newest files
Doc string

Delete older distributions

Options for rotate

Long
Short
Args
bool
DU
ST
Description
--match
-m
arg


ST
patterns to match (required)
--dist-dir
-d
arg


ST
directory where the distributions are
--keep
-k
arg


ST
number of matching distributions to keep

Command: saveopts


distutils
setuptools
Command defined in

ST
Description

save supplied options to setup.cfg or other config file
Doc string

Save command-line options to a file

Options for saveopts

Long
Short
Args
bool
DU
ST
Description
--global-config
-g

bool

ST
save options to the site-wide distutils.cfg file
--user-config
-u

bool

ST
save options to the current user's pydistutils.cfg file
--filename
-f
arg


ST
configuration file to use (default=setup.cfg)

Command: sdist


distutils
setuptools
Command defined in
DU
ST
Description
create a source distribution (tarball, zip file, etc.)
create a source distribution (tarball, zip file, etc.)
Doc string
[None]
Smart sdist that finds anything supported by revision control

Options for sdist

Long
Short
Args
bool
DU
ST
Description
--template
-t
arg

DU
x
name of manifest template file [default: MANIFEST.in]
--manifest
-m
arg

DU
x
name of manifest file [default: MANIFEST]
--use-defaults


bool
DU
x
include the default file set in the manifest [default; disable with --no-defaults]
--no-defaults



DU
x
don't include the default file set
--prune


bool
DU
x
specifically exclude files/directories that should not be distributed (build tree, RCS/CVS dirs, etc.) [default; disable with --no-prune]
--no-prune



DU
x
don't automatically exclude anything
--manifest-only
-o

bool
DU
x
just regenerate the manifest and then stop (implies --force-manifest)
--force-manifest
-f

bool
DU
x
forcibly regenerate the manifest and carry on as usual. Deprecated: now the manifest is always regenerated.
--formats

arg

DU
ST
formats for source distribution (comma-separated list)
--keep-temp
-k

bool
DU
ST
keep the distribution tree around after creating archive file(s)
--dist-dir
-d
arg

DU
ST
directory to put the source distribution archive(s) in [default: dist]
--metadata-check


bool
DU
x
Ensure that all required elements of meta-data are supplied. Warn if any missing. [default]
--help-formats



DU
ST
list available distribution formats

Command: setopt


distutils
setuptools
Command defined in

ST
Description

set an option in setup.cfg or another config file
Doc string

Save command-line options to a file

Options for setopt

Long
Short
Args
bool
DU
ST
Description
--command
-c
arg


ST
command to set an option for
--option
-o
arg


ST
option to set
--set-value
-s
arg


ST
value of the option
--remove
-r

bool

ST
remove (unset) the value
--global-config
-g

bool

ST
save options to the site-wide distutils.cfg file
--user-config
-u

bool

ST
save options to the current user's pydistutils.cfg file
--filename
-f
arg


ST
configuration file to use (default=setup.cfg)

Command: test


distutils
setuptools
Command defined in

ST
Description

run unit tests after in-place build
Doc string

Command to run unit tests after in-place build

Options for test

Long
Short
Args
bool
DU
ST
Description
--test-module
-m
arg


ST
Run 'test_suite' in specified module
--test-suite
-s
arg


ST
Test suite to run (e.g. 'some_module.test_suite')

Command: upload


distutils
setuptools
Command defined in
DU
du
Description
upload binary package to PyPI

Doc string
[None]

Options for upload

Long
Short
Args
bool
DU
ST
Description
--repository
-r
arg

DU
du
url of repository [default: http://pypi.python.org/pypi]
--show-response


bool
DU
du
display full response text from server
--sign
-s

bool
DU
du
sign files to upload using gpg
--identity
-i
arg

DU
du
GPG identity used to sign files

Command: upload_docs


distutils
setuptools
Command defined in

ST
Description

Upload documentation to PyPI
Doc string

[None]

Options for upload_docs

Long
Short
Args
bool
DU
ST
Description
--repository
-r
arg


ST
url of repository [default: http://pypi.python.org/pypi]
--show-response


bool

ST
display full response text from server
--upload-dir

arg


ST
directory to upload

setup( ) function

distutils.core.setup() doc string:

The gateway to the Distutils: do everything your setup script needs to do, in a highly flexible and user-driven way. Briefly: create a Distribution instance; find and parse config files; parse the command line; run each Distutils command found there, customized by the options supplied to 'setup()' (as keyword arguments), in config files, and on the command line.
The Distribution instance might be an instance of a class supplied via the 'distclass' keyword argument to 'setup'; if no such class is supplied, then the Distribution class (in dist.py) is instantiated. All other arguments to 'setup' (except for 'cmdclass') are used to set attributes of the Distribution instance.
The 'cmdclass' argument, if supplied, is a dictionary mapping command names to command classes. Each command encountered on the command line will be turned into a command class, which is in turn instantiated; any class found in 'cmdclass' is used in place of the default, which is (for command 'foo_bar') class 'foo_bar' in module 'distutils.command.foo_bar'. The command class must provide a 'user_options' attribute which is a list of option specifiers for 'distutils.fancy_getopt'. Any command-line options between the current and the next command are used to set attributes of the current command object.
When the entire command-line has been successfully parsed, calls the 'run()' method on each command object in turn. This method will be driven entirely by the Distribution object (which each command object has a reference to, thanks to its constructor), and the command-specific options that became attributes of each command object.

distutils and setuptools Distribution class doc strings:

distutils
The core of the Distutils. Most of the work hiding behind 'setup' is really done within a Distribution instance, which farms the work out to the Distutils commands specified on the command line.
Setup scripts will almost never instantiate Distribution directly, unless the 'setup()' function is totally inadequate to their needs. However, it is conceivable that a setup script might wish to subclass Distribution for some specialized purpose, and then pass the subclass to 'setup()' as the 'distclass' keyword argument. If so, it is necessary to respect the expectations that 'setup' has of Distribution. See the code for 'setup()', in core.py, for details.
setuptools
Distribution with support for features, tests, and package data
This is an enhanced version of 'distutils.dist.Distribution' that effectively adds the following new optional keyword arguments to 'setup()':
'install_requires' -- a string or sequence of strings specifying project versions that the distribution requires when installed, in the format used by 'pkg_resources.require()'. They will be installed automatically when the package is installed. If you wish to use packages that are not available in PyPI, or want to give your users an alternate download location, you can add a 'find_links' option to the '[easy_install]' section of your project's 'setup.cfg' file, and then setuptools will scan the listed web pages for links that satisfy the requirements.
'extras_require' -- a dictionary mapping names of optional "extras" to the additional requirement(s) that using those extras incurs. For example, this::
extras_require = dict(reST = ["docutils>=0.3", "reSTedit"])
indicates that the distribution can optionally provide an extra capability called "reST", but it can only be used if docutils and reSTedit are installed. If the user installs your package using EasyInstall and requests one of your extras, the corresponding additional requirements will be installed if needed.
'features' deprecated -- a dictionary mapping option names to 'setuptools.Feature' objects. Features are a portion of the distribution that can be included or excluded based on user options, inter-feature dependencies, and availability on the current system. Excluded features are omitted from all setup commands, including source and binary distributions, so you can create multiple distributions from the same source tree. Feature names should be valid Python identifiers, except that they may contain the '-' (minus) sign. Features can be included or excluded via the command line options '--with-X' and '--without-X', where 'X' is the name of the feature. Whether a feature is included by default, and whether you are allowed to control this from the command line, is determined by the Feature object. See the 'Feature' class for more information.
'test_suite' -- the name of a test suite to run for the 'test' command. If the user runs 'python setup.py test', the package will be installed, and the named test suite will be run. The format is the same as would be used on a 'unittest.py' command line. That is, it is the dotted name of an object to import and call to generate a test suite.
'package_data' -- a dictionary mapping package names to lists of filenames or globs to use to find data files contained in the named packages. If the dictionary has filenames or globs listed under '""' (the empty string), those names will be searched for in every package, in addition to any names for the specific package. Data files found using these names/globs will be installed along with the package, in the same location as the package. Note that globs are allowed to reference the contents of non-package subdirectories, as long as you use '/' as a path separator. (Globs are automatically converted to platform-specific paths at runtime.)
In addition to these new keywords, this class also has several new methods for manipulating the distribution's contents. For example, the 'include()' and 'exclude()' methods can be thought of as in-place add and subtract commands that add or remove packages, modules, extensions, and so on from the distribution. They are used by the feature subsystem to configure the distribution for the included and excluded features.

setup( ) function arguments

Keyword arguments to distutils.core.setup( ). All arguments are in general optional (which is why they are keyword arguments and not positional), though some are required depending on the command being executed.
Most of the arguments to setup( ) specify metadata about, or components to include in, the distribution package being prepared or installed.
Other arguments provide less-frequently needed functionality. For example, script_name and script_args can be used to supply as function arguments what setup( ) would normally get from the script's command line arguments.
(Note that in the docs that follow, "package" generally means "distribution package", not "module package" as found in the python language.)
Argument name
Type
Defn
Description
distclass
Unknown
DU
See Distribution class doc comment
script_name
str
DU
From class Distribution comments: 'script_name' and 'script_args' are usually defaulted to sys.argv[0] and sys.argv[1:], but they can be overridden [by supplying these arguments to setup()] when the caller is not necessarily a setup script run from the command-line.
script_args
str
DU
From class Distribution comments: 'script_name' and 'script_args' are usually defaulted to sys.argv[0] and sys.argv[1:], but they can be overridden [by supplying these arguments to setup()] when the caller is not necessarily a setup script run from the command-line.
options
list
DU
From Distribution.init(): ... if attr: looks like 'options' needs to be: [(commandname, (optname, optval))]
name
str
DU
package name
version
str
DU
package version
author
str
DU
author's name
author_email
str
DU
author's email address
maintainer
str
DU
maintainer's name
maintainer_email
str
DU
maintainer's email address
url
str
DU
URL for this package
license
str
DU
license of the package
description
str
DU
package description
long_description
str
DU
long package description
keywords
list
DU
list of keywords
platforms
list
DU
list of platforms
classifiers
list
DU
list of classifiers
download_url
str
DU

requires
list
DU
list of packages/modules required
provides
list
DU
list of packages/modules provided
obsoletes
list
DU
list of packages/modules made obsolete
cmdclass
dict

see setup() doc string
tests_require
?
ST
Argument check: Verify that install_requires is a valid requirements list
dependency_links
?
ST
Argument check: Verify that value is a string list or None
extras_require
?
ST
-- a dictionary mapping names of optional "extras" to the additional requirement(s) that using those extras incurs. For example, this::
extras_require = dict(reST = ["docutils>=0.3", "reSTedit"])
indicates that the distribution can optionally provide an extra capability called "reST", but it can only be used if docutils and reSTedit are installed. If the user installs your package using EasyInstall and requests one of your extras, the corresponding additional requirements will be installed if needed.
Argument check: Verify that extras_require mapping is valid
include_package_data
?
ST
Argument check: Verify that value is True, False, 0, or 1
use_2to3_fixers
?
ST
Argument check: Verify that value is a string list or None
test_loader
?
ST

eager_resources
?
ST
Argument check: Verify that value is a string list or None
namespace_packages
?
ST
Argument check: Verify that namespace packages are valid
convert_2to3_doctests
?
ST
Argument check: Verify that value is a string list or None
exclude_package_data
?
ST
Argument check: Verify that value is a dictionary of package names to glob lists
zip_safe
?
ST
Argument check: Verify that value is True, False, 0, or 1
package_data
?
ST
-- a dictionary mapping package names to lists of filenames or globs to use to find data files contained in the named packages. If the dictionary has filenames or globs listed under '""' (the empty string), those names will be searched for in every package, in addition to any names for the specific package. Data files found using these names/globs will be installed along with the package, in the same location as the package. Note that globs are allowed to reference the contents of non-package subdirectories, as long as you use '/' as a path separator. (Globs are automatically converted to platform-specific paths at runtime.)
Argument check: Verify that value is a dictionary of package names to glob lists
use_2to3_exclude_fixers
?
ST
Argument check: Verify that value is a string list or None
install_requires
?
ST
-- a string or sequence of strings specifying project versions that the distribution requires when installed, in the format used by 'pkg_resources.require()'. They will be installed automatically when the package is installed. If you wish to use packages that are not available in PyPI, or want to give your users an alternate download location, you can add a 'find_links' option to the '[easy_install]' section of your project's 'setup.cfg' file, and then setuptools will scan the listed web pages for links that satisfy the requirements.
Argument check: Verify that install_requires is a valid requirements list
entry_points
?
ST
Argument check: Verify that entry_points map is parseable
use_2to3
?
ST
Argument check: Verify that value is True, False, 0, or 1
test_suite
?
ST
-- the name of a test suite to run for the 'test' command. If the user runs 'python setup.py test', the package will be installed, and the named test suite will be run. The format is the same as would be used on a 'unittest.py' command line. That is, it is the dotted name of an object to import and call to generate a test suite.
packages
?
ST

Analysis of distutils and setuptools

  • My program: f:\Proj_Test\Python\setuptools_doc\setuptools_doc.py
  • Python version: 3.3.2 (v3.3.2:d047928ae3f6, May 16 2013, 00:03:43) [MSC v.1600 32 bit (Intel)]