Generated
2014-10-08 00:44:07
Python version
3.4.1 (v3.4.1:c0e311e010fc, May 18 2014, 10:45:13) [MSC v.1600 64 bit (AMD64)]
distutils version
3.4.1
setuptools version
2.1

Contents

Overview

This page presents combined detail documentation for the setup() function supplied by distutils and setuptools (plus wheel extension), including setup()'s arguments, the command-line arguments it digests and interprets as commands, and the arguments to those commands.
For an introduction to distutils and setuptools, please see the page: Python- distutils-setuptools introduction.
The information on this page has been gathered almost completely automatically from distutils and setuptools libraries, so should agree closely with actual behavior of those libraries. (See applicable version numbers, above.)

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 category
Command
DU
ST
Description
build
build
DU
du
build everything needed to install

build_clib
DU
du
build C/C++ libraries used by Python extensions

build_ext
DU
ST
build C/C++ extensions (compile/link to build directory)

build_py
DU
ST
"build" pure Python modules (copy to build directory)

build_scripts
DU
du
"build" scripts (copy and fixup #! line)

clean
DU
du
clean up temporary files from 'build' command

test

ST
run unit tests after in-place build
packaging
bdist
DU
du
create a built (binary) distribution

bdist_dumb
DU
du
create a "dumb" built distribution

bdist_egg

ST
create an "egg" distribution

bdist_rpm
DU
ST
create an RPM distribution

bdist_wheel


From addon wheel. create a wheel distribution

bdist_wininst
DU
ST
create an executable installer for MS Windows

check
DU
du
perform some checks on the package

egg_info

ST
create a distribution's .egg-info directory

sdist
DU
ST
create a source distribution (tarball, zip file, etc.)
PyPI
register
DU
ST
register the distribution with the Python package index

upload
DU
du
upload binary package to PyPI

upload_docs

ST
Upload documentation to PyPI
install
develop

ST
install package in 'development mode'

easy_install

ST
Find/get/install Python packages

install
DU
ST
install everything from build directory

install_data
DU
du
install data files

install_egg_info

ST
Install an .egg-info directory for the package

install_headers
DU
du
install C/C++ header files

install_lib
DU
ST
install all Python modules (extensions and pure Python)

install_scripts
DU
ST
install scripts (Python or otherwise)
misc
alias

ST
define a shortcut to invoke one or more commands

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
Key: DU and ST columns indicate for each command whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils.

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
--no-user-cfg


ignore pydistutils.cfg in your home directory
--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

Command defined in
Description
Docstring
setuptools
define a shortcut to invoke one or more commands
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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist

Command defined in
Description
Docstring
distutils
create a built (binary) distribution

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: win-amd64)
--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)
--owner
-u
arg

DU
du
Owner name used when creating a tar file [default: current user]
--group
-g
arg

DU
du
Group name used when creating a tar file [default: current group]
--help-formats



DU
du
lists available distribution formats
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist_dumb

Command defined in
Description
Docstring
distutils
create a "dumb" built distribution

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: win-amd64)
--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)
--owner
-u
arg

DU
du
Owner name used when creating a tar file [default: current user]
--group
-g
arg

DU
du
Group name used when creating a tar file [default: current group]
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist_egg

Command defined in
Description
Docstring
setuptools
create an "egg" distribution

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: win-amd64)
--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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist_rpm

Command defined in
Description
Docstring
distutils
create an RPM distribution

setuptools
create an RPM distribution

Options for bdist_rpm

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

arg


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

arg


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


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

arg


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




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




ST
only regenerate spec file
--source-only




ST
only generate source RPM
--binary-only




ST
only generate binary RPM
--use-bzip2




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

arg


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

arg


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

arg


ST
RPM release number
--serial

arg


ST
RPM serial number
--vendor

arg


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

arg


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

arg


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

arg


ST
RPM changelog
--icon

arg


ST
name of icon file
--provides

arg


ST
capabilities provided by this package
--requires

arg


ST
capabilities required by this package
--conflicts

arg


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

arg


ST
capabilities required to build this package
--obsoletes

arg


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


bool

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

bool

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




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


bool

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




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


bool

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




ST
RPM 2 compatibility mode
--prep-script

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

bool

ST
Run the INSTALL phase of RPM building in quiet mode
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist_wheel

Command defined in
Description
Docstring
Addon: wheel
create a wheel distribution

Options for bdist_wheel

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



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



platform name to embed in generated filenames (default: win-amd64)
--keep-temp
-k

bool


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



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


bool


skip rebuilding everything (for testing/debugging)
--relative


bool


build the archive using relative paths(default: false)
--owner
-u
arg



Owner name used when creating a tar file [default: current user]
--group
-g
arg



Group name used when creating a tar file [default: current group]
--universal


bool


make a universal wheel (default: false)
--python-tag

arg



Python implementation compatibility tag (default: py3)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: bdist_wininst

Command defined in
Description
Docstring
distutils
create an executable installer for MS Windows

setuptools
create an executable installer for MS Windows

Options for bdist_wininst

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

arg


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


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

bool

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

arg


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

bool

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

bool

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


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


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


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


bool

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

arg


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

arg


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


ST
specify Vista's UAC handling - 'none'/default=no handling, 'auto'=use UAC if target Python installed for all users, 'force'=always use UAC
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: build

Command defined in
Description
Docstring
distutils
build everything needed to install

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: win-amd64)
--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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: build_clib

Command defined in
Description
Docstring
distutils
build C/C++ libraries used by Python extensions

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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: build_ext

Command defined in
Description
Docstring
distutils
build C/C++ extensions (compile/link to build directory)

setuptools
build C/C++ extensions (compile/link to build directory)

Options for build_ext

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


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


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


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

bool

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


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


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


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


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


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


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


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

bool

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

bool

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


ST
specify the compiler type
--swig-cpp


bool

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

arg


ST
list of SWIG command line options
--swig

arg


ST
path to the SWIG executable
--user


bool

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




ST
list available compilers
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: build_py

Command defined in
Description
Docstring
distutils
"build" pure Python modules (copy to build directory)

setuptools
"build" pure Python modules (copy to build directory)
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


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

bool

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




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


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

bool

ST
forcibly build everything (ignore file timestamps)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: build_scripts

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

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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: check

Command defined in
Description
Docstring
distutils
perform some checks on the package
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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: clean

Command defined in
Description
Docstring
distutils
clean up temporary files from 'build' command

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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: develop

Command defined in
Description
Docstring
setuptools
install package in 'development mode'
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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: easy_install

Command defined in
Description
Docstring
setuptools
Find/get/install Python packages
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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: egg_info

Command defined in
Description
Docstring
setuptools
create a distribution's .egg-info directory

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]
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install

Command defined in
Description
Docstring
distutils
install everything from build directory

setuptools
install everything from build directory
Use easy_install to install the package, w/dependencies

Options for install

Long
Short
Args
bool
DU
ST
Description
--prefix

arg


ST
installation prefix
--exec-prefix

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


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

arg


ST
installation directory for Python scripts
--install-data

arg


ST
installation directory for data files
--compile
-c

bool

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




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


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

bool

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


bool

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

arg


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


bool

ST
install in user site-package 'C:\Users\graham\AppData\Roaming\Python\Python34\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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install_data

Command defined in
Description
Docstring
distutils
install data files

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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install_egg_info

Command defined in
Description
Docstring
setuptools
Install an .egg-info directory for the package
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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install_headers

Command defined in
Description
Docstring
distutils
install C/C++ header files

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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install_lib

Command defined in
Description
Docstring
distutils
install all Python modules (extensions and pure Python)

setuptools
install all Python modules (extensions and pure Python)
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


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


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

bool

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

bool

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




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


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


bool

ST
skip the build steps
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: install_scripts

Command defined in
Description
Docstring
distutils
install scripts (Python or otherwise)

setuptools
install scripts (Python or otherwise)
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


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


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

bool

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


bool

ST
skip the build steps
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: register

Command defined in
Description
Docstring
distutils
register the distribution with the Python package index

setuptools
register the distribution with the Python package index

Options for register

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


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


bool

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


bool

ST
list the valid Trove classifiers
--strict


bool

ST
Will stop the registering if the meta-data are not fully compliant
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: rotate

Command defined in
Description
Docstring
setuptools
delete older distributions, keeping N newest files
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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: saveopts

Command defined in
Description
Docstring
setuptools
save supplied options to setup.cfg or other config file
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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: sdist

Command defined in
Description
Docstring
distutils
create a source distribution (tarball, zip file, etc.)

setuptools
create a source distribution (tarball, zip file, etc.)
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


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

bool

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


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]
--owner
-u
arg

DU
X
Owner name used when creating a tar file [default: current user]
--group
-g
arg

DU
X
Group name used when creating a tar file [default: current group]
--help-formats




ST
list available distribution formats
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: setopt

Command defined in
Description
Docstring
setuptools
set an option in setup.cfg or another config file
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)
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: test

Command defined in
Description
Docstring
setuptools
run unit tests after in-place build
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')
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: upload

Command defined in
Description
Docstring
distutils
upload binary package to PyPI

Options for upload

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

DU
du
url of repository [default: https://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
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

Command: upload_docs

Command defined in
Description
Docstring
setuptools
Upload documentation to PyPI

Options for upload_docs

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


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


bool

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

arg


ST
directory to upload
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

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
entry_points
?
ST
Argument check: Verify that entry_points map is parseable
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
tests_require
?
ST
Argument check: Verify that install_requires is a valid requirements list
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.
convert_2to3_doctests
?
ST
Argument check: Verify that value is a string list or None
zip_safe
?
ST
Argument check: Verify that value is True, False, 0, or 1
namespace_packages
?
ST
Argument check: Verify that namespace packages are valid
packages
?
ST

use_2to3_exclude_fixers
?
ST
Argument check: Verify that value is a string list or None
use_2to3
?
ST
Argument check: Verify that value is True, False, 0, or 1
eager_resources
?
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
exclude_package_data
?
ST
Argument check: Verify that value is a dictionary of package names to glob lists
use_2to3_fixers
?
ST
Argument check: Verify that value is a string list or None
test_loader
?
ST

include_package_data
?
ST
Argument check: Verify that value is True, False, 0, or 1
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
dependency_links
?
ST
Argument check: Verify that value is a string list or None

Analysis of distutils and setuptools

  • My program: f:\Proj_Test\Python\setuptools_doc\setuptools_doc.py
  • Python version: 3.4.1 (v3.4.1:c0e311e010fc, May 18 2014, 10:45:13) [MSC v.1600 64 bit (AMD64)]