Installing and Using Setuptools
.. contents:: Table of Contents
The recommended way to bootstrap setuptools on any system is to download
ez_setup.py_ and run it using the target Python environment. Different
operating systems have different recommended techniques to accomplish this
basic routine, so below are some examples to get you started.
Setuptools requires Python 2.6 or later. To install setuptools
on Python 2.4 or Python 2.5, use the
bootstrap script for Setuptools 1.x
The link provided to ez_setup.py is a bookmark to bootstrap script for the latest known stable release.
.. _ez_setup.py: https://bootstrap.pypa.io/ez_setup.py
Windows (Powershell 3 or later)
For best results, uninstall previous versions FIRST (see
Using Windows 8 (which includes PowerShell 3) or earlier versions of Windows with PowerShell 3 installed, it’s possible to install with one simple Powershell command. Start up Powershell and paste this command::
> (Invoke-WebRequest https://bootstrap.pypa.io/ez_setup.py).Content | python -
.. image:: https://badges.gitter.im/pypa/setuptools.svg :alt: Join the chat at https://gitter.im/pypa/setuptools :target: https://gitter.im/pypa/setuptools?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
You must start the Powershell with Administrative privileges or you may choose to install a user-local installation::
> (Invoke-WebRequest https://bootstrap.pypa.io/ez_setup.py).Content | python - --user
If you have Python 3.3 or later, you can use the
py command to install to
different Python versions. For example, to install to Python 3.3 if you have
Python 2.7 installed::
> (Invoke-WebRequest https://bootstrap.pypa.io/ez_setup.py).Content | py -3 -
The recommended way to install setuptools on Windows is to download
ez_setup.py_ and run it. The script will download the appropriate
distribution file and install it for you.
Once installation is complete, you will find an
easy_install program in
Scripts subdirectory. For simple invocation and best results,
add this directory to your
PATH environment variable, if it is not already
present. If you did a user-local install, the
Scripts subdirectory is
For Windows without PowerShell 3 or for installation without a command-line,
ez_setup.py_ using your preferred web browser or other technique
and “run” that file.
Most Linux distributions come with wget.
ez_setup.py_ and run it using the target Python version. The script
will download the appropriate version and install it for you::
> wget https://bootstrap.pypa.io/ez_setup.py -O - | python
Note that you will may need to invoke the command with superuser privileges to install to the system Python::
> wget https://bootstrap.pypa.io/ez_setup.py -O - | sudo python
Alternatively, Setuptools may be installed to a user-local path::
> wget https://bootstrap.pypa.io/ez_setup.py -O - | python - --user
Note that on some older systems (noted on Debian 6 and CentOS 5 installations),
wget may refuse to download
ez_setup.py, complaining that the certificate common name
does not match the host name
bootstrap.pypa.io. In addition, the
ez_setup.py script may then encounter similar problems using
wget internally to download
setuptools-x.y.zip, complaining that the certificate common name of
www.python.org does not match the
pypi.python.org. Those are known issues, related to a bug in the older versions of
Issue 59 <https://bitbucket.org/pypa/pypi/issue/59#comment-5881915>_). If you happen to encounter them,
install Setuptools as follows::
> wget --no-check-certificate https://bootstrap.pypa.io/ez_setup.py > python ez_setup.py --insecure
Unix including Mac OS X (curl)
If your system has curl installed, follow the
wget instructions but
-o. For example::
> curl https://bootstrap.pypa.io/ez_setup.py -o - | python
For more advanced installation options, such as installing to custom
locations or prefixes, download and extract the source
Setuptools on PyPI <https://pypi.python.org/pypi/setuptools>_
and run setup.py with any supported distutils and Setuptools options.
setuptools-x.x$ python setup.py install --prefix=/opt/setuptools
--help to get a full options list, but we recommend consulting
EasyInstall manual_ for detailed instructions, especially
on custom installation locations_.
.. _EasyInstall manual: https://pythonhosted.org/setuptools/EasyInstall .. _the section on custom installation locations: https://pythonhosted.org/setuptools/EasyInstall#custom-installation-locations
All setuptools downloads can be found at
the project's home page in the Python
Package Index_. Scroll to the very bottom of the page to find the links.
.. _the project’s home page in the Python Package Index: https://pypi.python.org/pypi/setuptools
In addition to the PyPI downloads, the development version of
is available from the
Bitbucket repo, and in-development versions of the
0.6 branch are available as well.
On Windows, if Setuptools was installed using an
installer, simply use the uninstall feature of “Add/Remove Programs” in the
Otherwise, to uninstall Setuptools or Distribute, regardless of the Python
version, delete all
distribute* files and
directories from your system’s
(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.
Using Setuptools and EasyInstall
Here are some of the available manuals, tutorials, and other resources for learning about Setuptools, Python Eggs, and EasyInstall:
The EasyInstall user's guide and reference manual_
The setuptools Developer's Guide_
The pkg_resources API reference_
The Internal Structure of Python Eggs_
Questions, comments, and bug reports should be directed to the
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
setuptools bug tracker.
.. _setuptools bug tracker: https://github.com/pypa/setuptools/issues .. _The Internal Structure of Python Eggs: https://setuptools.readthedocs.io/en/latest/formats.html .. _The setuptools Developer’s Guide: https://setuptools.readthedocs.io/en/latest/developer-guide.html .. _The pkg_resources API reference: https://setuptools.readthedocs.io/en/latest/pkg_resources.html .. _The EasyInstall user’s guide and reference manual: https://setuptools.readthedocs.io/en/latest/easy_install.html .. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
The original design for the
.eggformat and the
pkg_resourcesAPI 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
.exewrappers 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!)
Tarek Ziadé is the principal author of the Distribute fork, which re-invigorated the community on the project, encouraged renewed innovation, and addressed many defects.
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.
Code of Conduct
Everyone interacting in the setuptools project’s codebases, issue trackers,
chat rooms, and mailing lists is expected to follow the
PyPA Code of Conduct_.
.. _PyPA Code of Conduct: https://www.pypa.io/en/latest/code-of-conduct/