setuptools-19.1.1.tar.gz

=============================== Installing and Using Setuptools =============================== .. contents:: **Table of Contents** `Change History <https://pythonhosted.org/setuptools/history.html>`_. ------------------------- Installation Instructions ------------------------- 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 <https://bitbucket.org/pypa/setuptools/raw/bootstrap-py24/ez_setup.py>`_. 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 `Uninstalling`_). 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 - 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 your Python ``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 ``$env:APPDATA\Python\Scripts``. Windows (simplified) ==================== For Windows without PowerShell 3 or for installation without a command-line, download `ez_setup.py`_ using your preferred web browser or other technique and "run" that file. Unix (wget) =========== Most Linux distributions come with wget. Download `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 `*.c.ssl.fastly.net` 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 host name `pypi.python.org`. Those are known issues, related to a bug in the older versions of `wget` (see `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 replace ``wget`` with ``curl`` and ``-O`` with ``-o``. For example:: > curl https://bootstrap.pypa.io/ez_setup.py -o - | python Advanced Installation ===================== For more advanced installation options, such as installing to custom locations or prefixes, download and extract the source tarball from `Setuptools on PyPI <https://pypi.python.org/pypi/setuptools>`_ and run setup.py with any supported distutils and Setuptools options. For example:: setuptools-x.x$ python setup.py install --prefix=/opt/setuptools Use ``--help`` to get a full options list, but we recommend consulting the `EasyInstall manual`_ for detailed instructions, especially `the section 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 Downloads ========= 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 ``setuptools`` is available from the `Bitbucket repo`_, and in-development versions of the `0.6 branch`_ are available as well. .. _Bitbucket repo: https://bitbucket.org/pypa/setuptools/get/default.tar.gz#egg=setuptools-dev .. _0.6 branch: http://svn.python.org/projects/sandbox/branches/setuptools-0.6/#egg=setuptools-dev06 Uninstalling ============ 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. -------------------------------- 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 `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`_. .. _setuptools bug tracker: https://bitbucket.org/pypa/setuptools/issues .. _The Internal Structure of Python Eggs: https://pythonhosted.org/setuptools/formats.html .. _The setuptools Developer's Guide: https://pythonhosted.org/setuptools/setuptools.html .. _The pkg_resources API reference: https://pythonhosted.org/setuptools/pkg_resources.html .. _The EasyInstall user's guide and reference manual: https://pythonhosted.org/setuptools/easy_install.html .. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/ ------- Credits ------- * The original design for the ``.egg`` format and the ``pkg_resources`` API was co-created by Phillip Eby and Bob Ippolito. Bob also implemented