The recommended way to install setuptools on Windows is to download
ez_setup.py and run it. The script will download the appropriate .egg
file and install it for you.

For best results, uninstall previous versions FIRST (see Uninstalling).

Once installation is complete, you will find an easy_install program in
your Python Scripts subdirectory. For simple invocation and best results,
add this directory to your PATH environment variable, if it is not already
present.

For more advanced installation options, such as installing to custom
locations or prefixes, download and extract the source
tarball from Setuptools on PyPI
and run setup.py with any supported distutils and Setuptools options.
For example:

On Windows, if Setuptools was installed using an .exe or .msi
installer, simply use the uninstall feature of “Add/Remove Programs” in the
Control Panel.

Otherwise, to uninstall Setuptools or Distribute, regardless of the Python
version, delete all setuptools* and distribute* files and
directories from your system’s site-packages directory
(and any other sys.path directories) FIRST.

If you are upgrading or otherwise plan to re-install Setuptools or Distribute,
nothing further needs to be done. If you want to completely remove Setuptools,
you may also want to remove the ‘easy_install’ and ‘easy_install-x.x’ scripts
and associated executables installed to the Python scripts directory.

Questions, comments, and bug reports should be directed to the distutils-sig
mailing list. If you have written (or know of) any tutorials, documentation,
plug-ins, or other resources for setuptools users, please let us know about
them there, so this reference list can be updated. If you have working,
tested patches to correct problems or add features, you may submit them to
the setuptools bug tracker.

The original design for the .egg format and the pkg_resources API was
co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first
version of pkg_resources, and supplied the OS X operating system version
compatibility algorithm.

Ian Bicking implemented many early “creature comfort” features of
easy_install, including support for downloading via Sourceforge and
Subversion repositories. Ian’s comments on the Web-SIG about WSGI
application deployment also inspired the concept of “entry points” in eggs,
and he has given talks at PyCon and elsewhere to inform and educate the
community about eggs and setuptools.

Jim Fulton contributed time and effort to build automated tests of various
aspects of easy_install, and supplied the doctests for the command-line
.exe wrappers on Windows.

Phillip J. Eby is the seminal author of setuptools, and
first proposed the idea of an importable binary distribution format for
Python application plug-ins.

Significant parts of the implementation of setuptools were funded by the Open
Source Applications Foundation, to provide a plug-in infrastructure for the
Chandler PIM application. In addition, many OSAF staffers (such as Mike
“Code Bear” Taylor) contributed their time and stress as guinea pigs for the
use of eggs and setuptools, even before eggs were “cool”. (Thanks, guys!)

Since the merge with Distribute, Jason R. Coombs is the
maintainer of setuptools. The project is maintained in coordination with
the Python Packaging Authority (PyPA) and the larger Python community.

1. Try ``getpreferredencoding``
2. If that returns US_ASCII or None, try the encoding from
``getdefaultlocale``. If that encoding was a "fallback" because Python
could not figure it out from the environment or OS, encoding remains
unresolved.
3. If the encoding is resolved, then make sure Python actually implements
the encoding.
4. On the event of an error or unknown codec, revert to fallbacks
(UTF-8 on Darwin, ASCII on everything else).
5. On the encoding is 'mac-roman' on Darwin, use UTF-8 as 'mac-roman' was
a bug on older Python releases.
On a side note, it would seem that the encoding only matters for when SVN
does not yet support ``--xml`` and when getting repository and svn version
numbers. The ``--xml`` technique should yield UTF-8 according to some
messages on the SVN mailing lists. So if the version numbers are always
7-bit ASCII clean, it may be best to only support the file parsing methods
for legacy SVN releases and support for SVN without the subprocess command
would simple go away as support for the older SVNs does.

Issue #26: Add support for SVN 1.7. Special thanks to Philip Thiem for the
contribution.

Issue #93: Wheels are now distributed with every release. Note that as
reported in Issue #108, as of Pip 1.4, scripts aren’t installed properly
from wheels. Therefore, if using Pip to install setuptools from a wheel,
the easy_install command will not be available.

Issue #60: On Windows, Setuptools supports deferring to another launcher,
such as Vinay Sajip’s pylauncher
(included with Python 3.3) to launch console and GUI scripts and not install
its own launcher executables. This experimental functionality is currently
only enabled if the SETUPTOOLS_LAUNCHER environment variable is set to
“natural”. In the future, this behavior may become default, but only after
it has matured and seen substantial adoption. The SETUPTOOLS_LAUNCHER
also accepts “executable” to force the default behavior of creating launcher
executables.

Issue #63: Bootstrap script (ez_setup.py) now prefers Powershell, curl, or
wget for retrieving the Setuptools tarball for improved security of the
install. The script will still fall back to a simple urlopen on
platforms that do not have these tools.

This release includes a couple of backward-incompatible changes, but most if
not all users will find 1.0 a drop-in replacement for 0.9.

Issue #50: Normalized API of environment marker support. Specifically,
removed line number and filename from SyntaxErrors when returned from
pkg_resources.invalid_marker. Any clients depending on the specific
string representation of exceptions returned by that function may need to
be updated to account for this change.

Added experimental environment marker support. Now clients may designate a
PEP-426 environment marker for “extra” dependencies. Setuptools uses this
feature in setup.py for optional SSL and certificate validation support
on older platforms. Based on Distutils-SIG discussions, the syntax is
somewhat tentative. There should probably be a PEP with a firmer spec before
the feature should be considered suitable for use.

Added support for SSL certificate validation when installing packages from
an HTTPS service.

Distribute #143: Launcher scripts, including easy_install itself, are now
accompanied by a manifest on 32-bit Windows environments to avoid the
Installer Detection Technology and thus undesirable UAC elevation described
in this Microsoft article.

Pull Request #35: In Buildout #64, it was reported that
under Python 3, installation of distutils scripts could attempt to copy
the __pycache__ directory as a file, causing an error, apparently only
under Windows. Easy_install now skips all directories when processing
metadata scripts.

Fix for encoding issue when installing from Windows executable on Python 3.

Distribute #323: Allow setup_requires requirements to supercede installed
requirements. Added some new keyword arguments to existing pkg_resources
methods. Also had to updated how __path__ is handled for namespace packages
to ensure that when a new egg distribution containing a namespace package is
placed on sys.path, the entries in __path__ are found in the same order they
would have been in had that egg been on the path when pkg_resources was
first imported.

Distribute #299: The develop command didn’t work on Python 3, when using 2to3,
as the egg link would go to the Python 2 source. Linking to the 2to3’d code
in build/lib makes it work, although you will have to rebuild the module
before testing it.

Distribute #183: Symlinked files are now extracted from source distributions.

Distribute #227: Easy_install fetch parameters are now passed during the
installation of a source distribution; now fulfillment of setup_requires
dependencies will honor the parameters passed to easy_install.

Distribute #99: now the standalone easy_install command doesn’t uses a
“setup.cfg” if any exists in the working directory. It will use it
only if triggered by install_requires from a setup.py call
(install, develop, etc).

Overhauled Windows script wrapping to support bdist_wininst better.
Scripts installed with bdist_wininst will always use #!python.exe or
#!pythonw.exe as the executable name (even when built on non-Windows
platforms!), and the wrappers will look for the executable in the script’s
parent directory (which should find the right version of Python).

Fix upload command not uploading files built by bdist_rpm or
bdist_wininst under Python 2.3 and 2.4.

Add support for “eggsecutable” headers: a #!/bin/sh script that is
prepended to an .egg file to allow it to be run as a script on Unix-ish
platforms. (This is mainly so that setuptools itself can have a single-file
installer on Unix, without doing multiple downloads, dealing with firewalls,
etc.)

Use cross-platform relative paths in easy-install.pth when doing
develop and the source directory is a subdirectory of the installation
target directory.

Fix a problem installing eggs with a system packaging tool if the project
contained an implicit namespace package; for example if the setup()
listed a namespace package foo.bar without explicitly listing foo
as a namespace package.

Fixed AttributeError when trying to download a setup_requires
dependency when a distribution lacks a dependency_links setting.

Made zip-safe and not-zip-safe flag files contain a single byte, so
as to play better with packaging tools that complain about zero-length
files.

Made setup.py develop respect the --no-deps option, which it
previously was ignoring.

Support extra_path option to setup() when install is run in
backward-compatibility mode.

Source distributions now always include a setup.cfg file that explicitly
sets egg_info options such that they produce an identical version number
to the source distribution’s version number. (Previously, the default
version number could be different due to the use of --tag-date, or if
the version was overridden on the command line that built the source
distribution.)

Allow .py files found by the include_package_data option to be
automatically included. Remove duplicate data file matches if both
include_package_data and package_data are used to refer to the same
files.

Added setuptools.file_finders entry point group to allow implementing
revision control plugins.

Added --identity option to upload command.

Added dependency_links to allow specifying URLs for --find-links.

Enhanced test loader to scan packages as well as modules, and call
additional_tests() if present to get non-unittest tests.

Support namespace packages in conjunction with system packagers, by omitting
the installation of any __init__.py files for namespace packages, and
adding a special .pth file to create a working package in
sys.modules.

Made --single-version-externally-managed automatic when --root is
used, so that most system packagers won’t require special support for
setuptools.

Fixed setup_requires, tests_require, etc. not using setup.cfg or
other configuration files for their option defaults when installing, and
also made the install use --multi-version mode so that the project
directory doesn’t need to support .pth files.

MANIFEST.in is now forcibly closed when any errors occur while reading
it. Previously, the file could be left open and the actual error would be
masked by problems trying to remove the open file on Windows systems.

The sdist command no longer uses the traditional MANIFEST file to
create source distributions. MANIFEST.in is still read and processed,
as are the standard defaults and pruning. But the manifest is built inside
the project’s .egg-info directory as SOURCES.txt, and it is rebuilt
every time the egg_info command is run.

Added the include_package_data keyword to setup(), allowing you to
automatically include any package data listed in revision control or
MANIFEST.in

Added the exclude_package_data keyword to setup(), allowing you to
trim back files included via the package_data and
include_package_data options.

Fixed --tag-svn-revision not working when run from a source
distribution.

Added warning for namespace packages with missing declare_namespace()

Added tests_require keyword to setup(), so that e.g. packages
requiring nose to run unit tests can make this dependency optional
unless the test command is run.

Made all commands that use easy_install respect its configuration
options, as this was causing some problems with setup.py install.

Added an unpack_directory() driver to setuptools.archive_util, so
that you can process a directory tree through a processing filter as if it
were a zipfile or tarfile.

Added an internal install_egg_info command to use as part of old-style
install operations, that installs an .egg-info directory with the
package.

Added a --single-version-externally-managed option to the install
command so that you can more easily wrap a “flat” egg in a system package.

Enhanced bdist_rpm so that it installs single-version eggs that
don’t rely on a .pth file. The --no-egg option has been removed,
since all RPMs are now built in a more backwards-compatible format.

Support full roundtrip translation of eggs to and from bdist_wininst
format. Running bdist_wininst on a setuptools-based package wraps the
egg in an .exe that will safely install it as an egg (i.e., with metadata
and entry-point wrapper scripts), and easy_install can turn the .exe
back into an .egg file or directory and install it as such.

Fixed some problems building extensions when Pyrex was installed, especially
with Python 2.4 and/or packages using SWIG.

Made develop command accept all the same options as easy_install,
and use the easy_install command’s configuration settings as defaults.

Made egg_info --tag-svn-revision fall back to extracting the revision
number from PKG-INFO in case it is being run on a source distribution of
a snapshot taken from a Subversion-based project.

Automatically detect .dll, .so and .dylib files that are being
installed as data, adding them to native_libs.txt automatically.

Fixed some problems with fresh checkouts of projects that don’t include
.egg-info/PKG-INFO under revision control and put the project’s source
code directly in the project directory. If such a package had any
requirements that get processed before the egg_info command can be run,
the setup scripts would fail with a “Missing ‘Version:’ header and/or
PKG-INFO file” error, because the egg runtime interpreted the unbuilt
metadata in a directory on sys.path (i.e. the current directory) as
being a corrupted egg. Setuptools now monkeypatches the distribution
metadata cache to pretend that the egg has valid version information, until
it has a chance to make it actually be so (via the egg_info command).

Added gui_scripts entry point group to allow installing GUI scripts
on Windows and other platforms. (The special handling is only for Windows;
other platforms are treated the same as for console_scripts.)

Added console_scripts entry point group to allow installing scripts
without the need to create separate script files. On Windows, console
scripts get an .exe wrapper so you can just type their name. On other
platforms, the scripts are written without a file extension.

Added support for building “old-style” RPMs that don’t install an egg for
the target package, using a --no-egg option.

The build_ext command now works better when using the --inplace
option and multiple Python versions. It now makes sure that all extensions
match the current Python version, even if newer copies were built for a
different Python version.

The upload command no longer attaches an extra .zip when uploading
eggs, as PyPI now supports egg uploads without trickery.

The ez_setup script/module now displays a warning before downloading
the setuptools egg, and attempts to check the downloaded egg against an
internal MD5 checksum table.

Fixed the --tag-svn-revision option of egg_info not finding the
latest revision number; it was using the revision number of the directory
containing setup.py, not the highest revision number in the project.

Added eager_resources setup argument

The sdist command now recognizes Subversion “deleted file” entries and
does not include them in source distributions.

setuptools now embeds itself more thoroughly into the distutils, so that
other distutils extensions (e.g. py2exe, py2app) will subclass setuptools’
versions of things, rather than the native distutils ones.

Added entry_points and setup_requires arguments to setup();
setup_requires allows you to automatically find and download packages
that are needed in order to build your project (as opposed to running it).

setuptools now finds its commands, setup() argument validators, and
metadata writers using entry points, so that they can be extended by
third-party packages. See Creating distutils Extensions
for more details.

The vestigial depends command has been removed. It was never finished
or documented, and never would have worked without EasyInstall - which it
pre-dated and was never compatible with.

Include svn:externals directories in source distributions as well as
normal subversion-controlled files and directories.

Added exclude=patternlist option to setuptools.find_packages()

Changed –tag-svn-revision to include an “r” in front of the revision number
for better readability.

Added ability to build eggs without including source files (except for any
scripts, of course), using the --exclude-source-files option to
bdist_egg.

setup.py install now automatically detects when an “unmanaged” package
or module is going to be on sys.path ahead of a package being installed,
thereby preventing the newer version from being imported. If this occurs,
a warning message is output to sys.stderr, but installation proceeds
anyway. The warning message informs the user what files or directories
need deleting, and advises them they can also use EasyInstall (with the
--delete-conflicting option) to do it automatically.

The egg_info command now adds a top_level.txt file to the metadata
directory that lists all top-level modules and packages in the distribution.
This is used by the easy_install command to find possibly-conflicting
“unmanaged” packages when installing the distribution.

Added zip_safe and namespace_packages arguments to setup().
Added package analysis to determine zip-safety if the zip_safe flag
is not given, and advise the author regarding what code might need changing.

The “egg_info” command now always sets the distribution metadata to “safe”
forms of the distribution name and version, so that distribution files will
be generated with parseable names (i.e., ones that don’t include ‘-‘ in the
name or version). Also, this means that if you use the various --tag
options of “egg_info”, any distributions generated will use the tags in the
version, not just egg distributions.

Added support for defining command aliases in distutils configuration files,
under the “[aliases]” section. To prevent recursion and to allow aliases to
call the command of the same name, a given alias can be expanded only once
per command-line invocation. You can define new aliases with the “alias”
command, either for the local, global, or per-user configuration.

Added “rotate” command to delete old distribution files, given a set of
patterns to match and the number of files to keep. (Keeps the most
recently-modified distribution files matching each pattern.)

Added “saveopts” command that saves all command-line options for the current
invocation to the local, global, or per-user configuration file. Useful for
setting defaults without having to hand-edit a configuration file.

Added a “setopt” command that sets a single option in a specified distutils
configuration file.

Beefed up the “sdist” command so that if you don’t have a MANIFEST.in, it
will include all files under revision control (CVS or Subversion) in the
current directory, and it will regenerate the list every time you create a
source distribution, not just when you tell it to. This should make the
default “do what you mean” more often than the distutils’ default behavior
did, while still retaining the old behavior in the presence of MANIFEST.in.

Fixed the “develop” command always updating .pth files, even if you
specified -n or --dry-run.

Slightly changed the format of the generated version when you use
--tag-build on the “egg_info” command, so that you can make tagged
revisions compare lower than the version specified in setup.py (e.g. by
using --tag-build=dev).

Added develop command to setuptools-based packages. This command
installs an .egg-link pointing to the package’s source directory, and
script wrappers that execfile() the source versions of the package’s
scripts. This lets you put your development checkout(s) on sys.path without
having to actually install them. (To uninstall the link, use
use setup.py develop --uninstall.)

Added egg_info command to setuptools-based packages. This command
just creates or updates the “projectname.egg-info” directory, without
building an egg. (It’s used by the bdist_egg, test, and develop
commands.)

Enhanced the test command so that it doesn’t install the package, but
instead builds any C extensions in-place, updates the .egg-info
metadata, adds the source directory to sys.path, and runs the tests
directly on the source. This avoids an “unmanaged” installation of the
package to site-packages or elsewhere.

Made easy_install a standard setuptools command, moving it from
the easy_install module to setuptools.command.easy_install. Note
that if you were importing or extending it, you must now change your imports
accordingly. easy_install.py is still installed as a script, but not as
a module.

Setup scripts using setuptools can now list their dependencies directly in
the setup.py file, without having to manually create a depends.txt file.
The install_requires and extras_require arguments to setup()
are used to create a dependencies file automatically. If you are manually
creating depends.txt right now, please switch to using these setup
arguments as soon as practical, because depends.txt support will be
removed in the 0.6 release cycle. For documentation on the new arguments,
see the setuptools.dist.Distribution class.

Setup scripts using setuptools now always install using easy_install
internally, for ease of uninstallation and upgrading.

Added support for “self-installation” bootstrapping. Packages can now
include ez_setup.py in their source distribution, and add the following
to their setup.py, in order to automatically bootstrap installation of
setuptools as part of their setup process:

Added ez_setup.py installer/bootstrap script to make initial setuptools
installation easier, and to allow distributions using setuptools to avoid
having to include setuptools in their source distribution.

All downloads are now managed by the PackageIndex class (which is now
subclassable and replaceable), so that embedders can more easily override
download logic, give download progress reports, etc. The class has also
been moved to the new setuptools.package_index module.

The Installer class no longer handles downloading, manages a temporary
directory, or tracks the zip_ok option. Downloading is now handled
by PackageIndex, and Installer has become an easy_install
command class based on setuptools.Command.

There is a new setuptools.sandbox.run_setup() API to invoke a setup
script in a directory sandbox, and a new setuptools.archive_util module
with an unpack_archive() API. These were split out of EasyInstall to
allow reuse by other tools and applications.

setuptools.Command now supports reinitializing commands using keyword
arguments to set/reset options. Also, Command subclasses can now set
their command_consumes_arguments attribute to True in order to
receive an args option containing the rest of the command line.

Added new options to bdist_egg to allow tagging the egg’s version number
with a subversion revision number, the current date, or an explicit tag
value. Run setup.py bdist_egg --help to get more information.