+Easy Install is a python module (``easy_install``) bundled with ``setuptools``
+that lets you automatically download, build, install, and manage Python
+(Please share your experiences with us! Whether you encountered success or
+difficulty installing a particular package, please add your notes to the
+`Experience Reports <http://peak.telecommunity.com/DevCenter/PackageNotes>`_
+page. You'll need to register for a Wiki ID if you don't already have one; you
+can do that from the `User Preferences
+<http://peak.telecommunity.com/DevCenter/UserPreferences>`_ page. Thanks!)
+(Also, if you'd like to learn about how you can use ``setuptools`` to make your
+own packages work better with EasyInstall, or provide EasyInstall-like features
+without requiring your users to use EasyInstall directly, you'll probably want
+to check out the full `setuptools`_ documentation as well.)
+.. contents:: **Table of Contents**
+.. _installation instructions:
+Installing "Easy Install"
+Download `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_, and
+run it; this will download and install the appropriate ``setuptools`` egg for
+your Python version. (You will need at least Python 2.3.5, or if you are on a
+64-bit platform, Python 2.4.) An ``easy_install`` script will be installed in
+the normal location for Python scripts on your platform. (Windows users, don't
+put ``ez_setup.py`` inside your Python installation; please put it in some
+other directory before running it.)
+You may receive a message telling you about an obsolete version of setuptools
+being present; if so, you must be sure to delete it entirely, along with the
+old ``pkg_resources`` module if it's present on ``sys.path``.
+The ``ez_setup.py`` script accepts the same `Command-Line Options`_ and
+`Configuration Files`_ as ``easy_install`` itself, so you can use them to
+control its behavior. In particular, you can use the --script-dir option to
+direct script installation to a custom location. You should not, however,
+use custom installation locations without first reading the section below on
+`Custom Installation Locations`_.
+The instructions you've just read assume that:
+* You are installling to Python's primary ``site-packages`` directory
+* You have unrestricted internet access on the computer where you are
+If you are behind an NTLM-based firewall that prevents Python programs from
+accessing the net directly, you may wish to first install and use the `APS
+proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such firewalls
+in the same way that your web browser(s) do. This will let ``ez_setup.py``
+download the setuptools egg.
+If you can't use APS, or don't have internet access at all, you will need to
+first download the appropriate ``.egg`` file from the `setuptools PyPI page
+<http://cheeseshop.python.org/pypi/setuptools>`_ using a computer with internet
+access. Place the egg in the same directory as ``ez_setup.py`` on the target
+computer before running it.
+If you are installing to a custom location or do not have write access to
+Python's primary ``site-packages`` directory, please also see the section below
+on `Custom Installation Locations`_ for more detailed instructions.
+If EasyInstall/setuptools appears to install correctly, and you can run the
+``easy_install`` command but it fails with an ``ImportError``, the most likely
+cause is that you installed to a location other than ``site-packages``,
+without taking any of the steps described in the `Custom Installation
+Locations`_ section below. Please see that section and follow the steps to
+make sure that your custom location will work correctly. Then re-install.
+Similarly, if you can run ``easy_install``, and it appears to be installing
+packages, but then you can't import them, the most likely issue is that you
+installed EasyInstall correctly but are using it to install packages to a
+non-standard location that hasn't been properly prepared. Again, see the
+section on `Custom Installation Locations`_ for more details.
+On Windows, an ``easy_install.exe`` launcher will also be installed, so that
+you can just type ``easy_install`` as long as it's on your ``PATH``. If typing
+``easy_install`` at the command prompt doesn't work, check to make sure your
+``PATH`` includes the appropriate ``C:\\Python2X\\Scripts`` directory. On
+most current versions of Windows, you can change the ``PATH`` by right-clicking
+"My Computer", choosing "Properties" and selecting the "Advanced" tab, then
+clicking the "Environment Variables" button. ``PATH`` will be in the "System
+Variables" section, and you will need to exit and restart your command shell
+(command.com, cmd.exe, bash, or other) for the change to take effect. Be sure
+to add a ``;`` after the last item on ``PATH`` before adding the scripts
+Note that instead of changing your ``PATH`` to include the Python scripts
+directory, you can also retarget the installation location for scripts so they
+go on a directory that's already on the ``PATH``. For more information see the
+sections below on `Command-Line Options`_ and `Configuration Files`_. You
+can pass command line options (such as ``--script-dir``) to ``ez_setup.py`` to
+control where ``easy_install.exe`` will be installed.
+Downloading and Installing a Package
+For basic use of ``easy_install``, you need only supply the filename or URL of
+a source distribution or .egg file (`Python Egg`__).
+**Example 1**. Install a package by name, searching PyPI for the latest
+version, and automatically downloading, building, and installing it::
+**Example 2**. Install or upgrade a package by name and version by finding
+links on a given "download page"::
+ easy_install -f http://pythonpaste.org/package_index.html SQLObject
+**Example 3**. Download a source distribution from a specified URL,
+automatically building and installing it::
+ easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
+**Example 4**. Install an already-downloaded .egg file::
+ easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
+**Example 5**. Upgrade an already-installed package to the latest version
+ easy_install --upgrade PyProtocols
+**Example 6**. Install a source distribution that's already downloaded and
+extracted in the current directory (New in 0.5a9)::
+**Example 7**. (New in 0.6a1) Find a source distribution or Subversion
+checkout URL for a package, and extract it or check it out to
+``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
+can be examined or edited. (The package will not be installed, but it can
+easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing
+and Viewing Source Packages`_ below for more info.)::
+ easy_install --editable --build-directory ~/projects SQLObject
+Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
+"distribution" names), and package+version specifiers. In each case, it will
+attempt to locate the latest available version that meets your criteria.
+When downloading or processing downloaded files, Easy Install recognizes
+distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
+.tar.bz2, or .zip. And of course it handles already-built .egg
+distributions as well as ``.win32.exe`` installers built using distutils.
+By default, packages are installed to the running Python installation's
+``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
+option to specify an alternative directory, or specify an alternate location
+using distutils configuration files. (See `Configuration Files`_, below.)
+By default, any scripts included with the package are installed to the running
+Python installation's standard script installation location. However, if you
+specify an installation directory via the command line or a config file, then
+the default directory for installing scripts will be the same as the package
+installation directory, to ensure that the script will have access to the
+installed package. You can override this using the ``-s`` or ``--script-dir``
+Installed packages are added to an ``easy-install.pth`` file in the install
+directory, so that Python will always use the most-recently-installed version
+of the package. If you would like to be able to select which version to use at
+runtime, you should use the ``-m`` or ``--multi-version`` option.
+You don't need to do anything special to upgrade a package: just install the
+new version, either by requesting a specific version, e.g.::
+ easy_install "SomePackage==2.0"
+a version greater than the one you have now::
+ easy_install "SomePackage>2.0"
+using the upgrade flag, to find the latest available version on PyPI::
+ easy_install --upgrade SomePackage
+or by using a download page, direct download URL, or package filename::
+ easy_install -f http://example.com/downloads ExamplePackage
+ easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg
+ easy_install my_downloads/ExamplePackage-2.0.tgz
+If you're using ``-m`` or ``--multi-version`` , using the ``require()``
+function at runtime automatically selects the newest installed version of a
+package that meets your version criteria. So, installing a newer version is
+the only step needed to upgrade such packages.
+If you're installing to a directory on PYTHONPATH, or a configured "site"
+directory (and not using ``-m``), installing a package automatically replaces
+any previous version in the ``easy-install.pth`` file, so that Python will
+import the most-recently installed version by default. So, again, installing
+the newer version is the only upgrade step needed.
+If you haven't suppressed script installation (using ``--exclude-scripts`` or
+``-x``), then the upgraded version's scripts will be installed, and they will
+be automatically patched to ``require()`` the corresponding version of the
+package, so that you can use them even if they are installed in multi-version
+``easy_install`` never actually deletes packages (unless you're installing a
+package with the same name and version number as an existing package), so if
+you want to get rid of older versions of a package, please see `Uninstalling
+Changing the Active Version
+If you've upgraded a package, but need to revert to a previously-installed
+version, you can do so like this::
+ easy_install PackageName==1.2.3
+Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
+If a package matching the requested name and version is not already installed
+in a directory on ``sys.path``, it will be located via PyPI and installed.
+If you'd like to switch to the latest installed version of ``PackageName``, you
+ easy_install PackageName
+This will activate the latest installed version. (Note: if you have set any
+``find_links`` via distutils configuration files, those download pages will be
+checked for the latest available version of the package, and it will be
+downloaded and installed if it is newer than your current version.)
+Note that changing the active version of a package will install the newly
+active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
+If you have replaced a package with another version, then you can just delete
+the package(s) you don't need by deleting the PackageName-versioninfo.egg file
+or directory (found in the installation directory).
+If you want to delete the currently installed version of a package (or all
+versions of a package), you should first run::
+ easy_install -m PackageName
+This will ensure that Python doesn't continue to search for a package you're
+planning to remove. After you've done this, you can safely delete the .egg
+files or directories, along with any scripts you wish to remove.
+Whenever you install, upgrade, or change versions of a package, EasyInstall
+automatically installs the scripts for the selected package version, unless
+you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in
+the script directory have the same name, they are overwritten.
+Thus, you do not normally need to manually delete scripts for older versions of
+a package, unless the newer version of the package does not include a script
+of the same name. However, if you are completely uninstalling a package, you
+may wish to manually delete its scripts.
+EasyInstall's default behavior means that you can normally only run scripts
+from one version of a package at a time. If you want to keep multiple versions
+of a script available, however, you can simply use the ``--multi-version`` or
+``-m`` option, and rename the scripts that EasyInstall creates. This works
+because EasyInstall installs scripts as short code stubs that ``require()`` the
+matching version of the package the script came from, so renaming the script
+has no effect on what it executes.
+For example, suppose you want to use two versions of the ``rst2html`` tool
+provided by the `docutils <http://docutils.sf.net/>`_ package. You might
+first install one version::
+ easy_install -m docutils==0.3.9
+then rename the ``rst2html.py`` to ``r2h_039``, and install another version::
+ easy_install -m docutils==0.3.10
+This will create another ``rst2html.py`` script, this one using docutils
+version 0.3.10 instead of 0.3.9. You now have two scripts, each using a
+different version of the package. (Notice that we used ``-m`` for both
+installations, so that Python won't lock us out of using anything but the most
+recently-installed version of the package.)
+Multiple Python Versions
+As of version 0.6a11, EasyInstall installs itself under two names:
+``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
+used to install it. Thus, if you install EasyInstall for both Python 2.3 and
+2.4, you can use the ``easy_install-2.3`` or ``easy_install-2.4`` scripts to
+install packages for Python 2.3 or 2.4, respectively.
+Restricting Downloads with ``--allow-hosts``
+You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
+EasyInstall will look for links and downloads on. ``--allow-hosts=None``
+prevents downloading altogether. You can also use wildcards, for example
+to restrict downloading to hosts in your own intranet. See the section below
+on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.
+By default, there are no host restrictions in effect, but you can change this
+default by editing the appropriate `configuration files`_ and adding::
+ allow_hosts = *.myintranet.example.com,*.python.org
+The above example would then allow downloads only from hosts in the
+``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
+Installing on Un-networked Machines
+Just copy the eggs or source packages you need to a directory on the target
+machine, then use the ``-f`` or ``--find-links`` option to specify that
+directory's location. For example::
+ easy_install -H None -f somedir SomePackage
+will attempt to install SomePackage using only eggs and source packages found
+in ``somedir`` and disallowing all remote access. You should of course make
+sure you have all of SomePackage's dependencies available in somedir.
+If you have another machine of the same operating system and library versions
+(or if the packages aren't platform-specific), you can create the directory of
+eggs using a command like this::
+ easy_install -zmaxd somedir SomePackage
+This will tell EasyInstall to put zipped eggs or source packages for
+SomePackage and all its dependencies into ``somedir``, without creating any
+scripts or .pth files. You can then copy the contents of ``somedir`` to the
+target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which
+prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
+even if they're installed elsewhere on the machine, and ``-d`` indicates the
+directory to place the eggs in.)
+Packaging Others' Projects As Eggs
+Need to distribute a package that isn't published in egg form? You can use
+EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``,
+``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
+``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location
+where you'd like the eggs placed. By placing them in a directory that is
+published to the web, you can then make the eggs available for download, either
+in an intranet or to the internet at large.
+If someone distributes a package in the form of a single ``.py`` file, you can
+wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
+So, something like this::
+ easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+will install the package as an egg, and this::
+ -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+will create a ``.egg`` file in the current directory.
+Creating your own Package Index
+In addition to local directories and the Python Package Index, EasyInstall can
+find download links on most any web page whose URL is given to the ``-f``
+(``--find-links``) option. In the simplest case, you can simply have a web
+page with links to eggs or Python source packages, even an automatically
+generated directory listing (such as the Apache web server provides).
+If you are setting up an intranet site for package downloads, you may want to
+configure the target machines to use your download site by default, adding
+something like this to their `configuration files`_::
+ find_links = http://mypackages.example.com/somedir/
+As you can see, you can list multiple URLs separated by whitespace, continuing
+on multiple lines if necessary (as long as the subsequent lines are indented.
+Controlling Build Options
+EasyInstall respects standard distutils `Configuration Files`_, so you can use
+them to configure build options for packages that it installs from source. For
+example, if you are on Windows using the MinGW compiler, you can configure the
+default compiler by putting something like this::
+into the appropriate distutils configuration file. In fact, since this is just
+normal distutils configuration, it will affect any builds using that config
+file, not just ones done by EasyInstall. For example, if you add those lines
+to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
+default compiler for *all* packages you build. See `Configuration Files`_
+below for a list of the standard configuration file locations, and links to
+more documentation on using distutils configuration files.
+Editing and Viewing Source Packages
+Sometimes a package's source distribution contains additional documentation,
+examples, configuration files, etc., that are not part of its actual code. If
+you want to be able to examine these files, you can use the ``--editable``
+option to EasyInstall, and EasyInstall will look for a source distribution
+or Subversion URL for the package, then download and extract it or check it out
+as a subdirectory of the ``--build-directory`` you specify. If you then wish
+to install the package after editing or configuring it, you can do so by
+rerunning EasyInstall with that directory as the target.
+Note that using ``--editable`` stops EasyInstall from actually building or
+installing the package; it just finds, obtains, and possibly unpacks it for
+you. This allows you to make changes to the package if necessary, and to
+either install it in development mode using ``setup.py develop`` (if the
+package uses setuptools, that is), or by running ``easy_install projectdir``
+(where ``projectdir`` is the subdirectory EasyInstall created for the
+In order to use ``--editable`` (``-e`` for short), you *must* also supply a
+``--build-directory`` (``-b`` for short). The project will be placed in a
+subdirectory of the build directory. The subdirectory will have the same
+name as the project itself, but in all-lowercase. If a file or directory of
+that name already exists, EasyInstall will print an error message and exit.
+Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
+You *must* specify project names (and optional version requirements) so that
+EasyInstall knows what directory name(s) to create. If you need to force
+EasyInstall to use a particular URL or filename, you should specify it as a
+``--find-links`` item (``-f`` for short), and then also specify
+the project name, e.g.::
+ easy_install -eb ~/projects \
+ -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
+Dealing with Installation Conflicts
+(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
+people using older versions of EasyInstall can consult it. As of version
+0.6a11, installation conflicts are handled automatically without deleting the
+old or system-installed packages, and without ignoring the issue. Instead,
+eggs are automatically shifted to the front of ``sys.path`` using special
+code added to the ``easy-install.pth`` file. So, if you are using version
+0.6a11 or better of setuptools, you do not need to worry about conflicts,
+and the following issues do not apply to you.)
+EasyInstall installs distributions in a "managed" way, such that each
+distribution can be independently activated or deactivated on ``sys.path``.
+However, packages that were not installed by EasyInstall are "unmanaged",
+in that they usually live all in one directory and cannot be independently
+activated or deactivated.
+As a result, if you are using EasyInstall to upgrade an existing package, or
+to install a package with the same name as an existing package, EasyInstall
+will warn you of the conflict. (This is an improvement over ``setup.py
+install``, becuase the ``distutils`` just install new packages on top of old
+ones, possibly combining two unrelated packages or leaving behind modules that
+have been deleted in the newer version of the package.)
+By default, EasyInstall will stop the installation if it detects a conflict
+between an existing, "unmanaged" package, and a module or package in any of
+the distributions you're installing. It will display a list of all of the
+existing files and directories that would need to be deleted for the new
+package to be able to function correctly. You can then either delete these
+conflicting files and directories yourself and re-run EasyInstall, or you can
+just use the ``--delete-conflicting`` or ``--ignore-conflicts-at-my-risk``
+options, as described under `Command-Line Options`_, below.
+Of course, once you've replaced all of your existing "unmanaged" packages with
+versions managed by EasyInstall, you won't have any more conflicts to worry
+EasyInstall tries to install packages in zipped form, if it can. Zipping
+packages can improve Python's overall import performance if you're not using
+the ``--multi-version`` option, because Python processes zipfile entries on
+``sys.path`` much faster than it does directories.
+As of version 0.5a9, EasyInstall analyzes packages to determine whether they
+can be safely installed as a zipfile, and then acts on its analysis. (Previous
+versions would not install a package as a zipfile unless you used the
+The current analysis approach is fairly conservative; it currenly looks for:
+ * Any use of the ``__file__`` or ``__path__`` variables (which should be
+ replaced with ``pkg_resources`` API calls)
+ * Possible use of ``inspect`` functions that expect to manipulate source files
+ (e.g. ``inspect.getsource()``)
+ * Any data files or C extensions (this restriction will be removed in a future
+ release, once the ``pkg_resources`` runtime has been hardened for multi-user
+If any of the above are found in the package being installed, EasyInstall will
+assume that the package cannot be safely run from a zipfile, and unzip it to
+a directory instead. You can override this analysis with the ``-zip-ok`` flag,
+which will tell EasyInstall to install the package as a zipfile anyway. Or,
+you can use the ``--always-unzip`` flag, in which case EasyInstall will always
+unzip, even if its analysis says the package is safe to run as a zipfile.
+Normally, however, it is simplest to let EasyInstall handle the determination
+of whether to zip or unzip, and only specify overrides when needed to work
+around a problem. If you find you need to override EasyInstall's guesses, you
+may want to contact the package author and the EasyInstall maintainers, so that
+they can make appropriate changes in future versions.
+(Note: If a package uses ``setuptools`` in its setup script, the package author
+has the option to declare the package safe or unsafe for zipped usage via the
+``zip_safe`` argument to ``setup()``. If the package author makes such a
+declaration, EasyInstall believes the package's author and does not perform its
+own analysis. However, your command-line option, if any, will still override
+the package author's choice.)
+You may specify default options for EasyInstall using the standard
+distutils configuration files, under the command heading ``easy_install``.
+EasyInstall will look first for a ``setup.cfg`` file in the current directory,
+then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
+and Windows, respectively), and finally a ``distutils.cfg`` file in the
+``distutils`` package directory. Here's a simple example::
+ # set the default location to install packages
+ install_dir = /home/me/lib/python
+ # Notice that indentation can be used to continue an option
+ # value; this is especially useful for the "--find-links"
+ # option, which tells easy_install to use download links on
+ # these pages before consulting PyPI:
+ find_links = http://sqlobject.org/
+In addition to accepting configuration for its own options under
+``[easy_install]``, EasyInstall also respects defaults specified for other
+distutils commands. For example, if you don't set an ``install_dir`` for
+``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
+command, this will become EasyInstall's default installation directory. Thus,
+if you are already using distutils configuration files to set default install
+locations, build options, etc., EasyInstall will respect your existing settings
+until and unless you override them explicitly in an ``[easy_install]`` section.
+For more information, see also the current Python documentation on the `use and
+location of distutils configuration files <http://docs.python.org/inst/config-syntax.html>`_.
+ Install all packages as zip files, even if they are marked as unsafe for
+ running as a zipfile. This can be useful when EasyInstall's analysis
+ of a non-setuptools package is too conservative, but keep in mind that
+ the package may not work correctly. (Changed in 0.5a9; previously this
+ option was required in order for zipped installation to happen at all.)
+ Don't install any packages as zip files, even if the packages are marked
+ as safe for running as a zipfile. This can be useful if a package does
+ something unsafe, but not in a way that EasyInstall can easily detect.
+ EasyInstall's default analysis is currently very conservative, however, so
+ you should only use this option if you've had problems with a particular
+ package, and *after* reporting the problem to the package's maintainer and
+ to the EasyInstall maintainers.
+ (Note: the ``-z/-Z`` options only affect the installation of newly-built
+ or downloaded packages that are not already installed in the target
+ directory; if you want to convert an existing installed version from
+ zipped to unzipped or vice versa, you'll need to delete the existing
+ version first, and re-run EasyInstall.)
+ "Multi-version" mode. Specifying this option prevents ``easy_install`` from
+ adding an ``easy-install.pth`` entry for the package being installed, and
+ if an entry for any version the package already exists, it will be removed
+ upon successful installation. In multi-version mode, no specific version of
+ the package is available for importing, unless you use
+ ``pkg_resources.require()`` to put it on ``sys.path``. This can be as
+ from pkg_resources import require
+ require("SomePackage", "OtherPackage", "MyPackage")
+ which will put the latest installed version of the specified packages on
+ ``sys.path`` for you. (For more advanced uses, like selecting specific
+ versions and enabling optional dependencies, see the ``pkg_resources`` API
+ Changed in 0.6a10: this option is no longer silently enabled when
+ installing to a non-PYTHONPATH, non-"site" directory. You must always
+ explicitly use this option if you want it to be active.
+``--upgrade, -U`` (New in 0.5a4)
+ By default, EasyInstall only searches online if a project/version
+ requirement can't be met by distributions already installed
+ on sys.path or the installation directory. However, if you supply the
+ ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
+ index and ``--find-links`` URLs before selecting a version to install. In
+ this way, you can force EasyInstall to use the latest available version of
+ any package it installs (subject to any version requirements that might
+ exclude such later versions).
+``--install-dir=DIR, -d DIR``
+ Set the installation directory. It is up to you to ensure that this
+ directory is on ``sys.path`` at runtime, and to use
+ ``pkg_resources.require()`` to enable the installed package(s) that you
+ (New in 0.4a2) If this option is not directly specified on the command line
+ or in a distutils configuration file, the distutils default installation
+ location is used. Normally, this would be the ``site-packages`` directory,
+ but if you are using distutils configuration files, setting things like
+ ``prefix`` or ``install_lib``, then those settings are taken into
+ account when computing the default installation directory, as is the
+``--script-dir=DIR, -s DIR``
+ Set the script installation directory. If you don't supply this option
+ (via the command line or a configuration file), but you *have* supplied
+ an ``--install-dir`` (via command line or config file), then this option
+ defaults to the same directory, so that the scripts will be able to find
+ their associated package installation. Otherwise, this setting defaults
+ to the location where the distutils would normally install scripts, taking
+ any distutils configuration file settings into account.
+ Don't install scripts. This is useful if you need to install multiple
+ versions of a package, but do not want to reset the version that will be
+ run by scripts that are already installed.
+``--always-copy, -a`` (New in 0.5a4)
+ Copy all needed distributions to the installation directory, even if they
+ are already present in a directory on sys.path. In older versions of
+ EasyInstall, this was the default behavior, but now you must explicitly
+ request it. By default, EasyInstall will no longer copy such distributions
+ from other sys.path directories to the installation directory, unless you
+ explicitly gave the distribution's filename on the command line.
+ Note that as of 0.6a10, using this option excludes "system" and
+ "development" eggs from consideration because they can't be reliably
+ copied. This may cause EasyInstall to choose an older version of a package
+ than what you expected, or it may cause downloading and installation of a
+ fresh copy of something that's already installed. You will see warning
+ messages for any eggs that EasyInstall skips, before it falls back to an
+ older version or attempts to download a fresh copy.
+``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
+ Scan the specified "download pages" or directories for direct links to eggs
+ or other distributions. Any existing file or directory names or direct
+ download URLs are immediately added to EasyInstall's search cache, and any
+ indirect URLs (ones that don't point to eggs or other recognized archive
+ formats) are added to a list of additional places to search for download
+ links. As soon as EasyInstall has to go online to find a package (either
+ because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
+ used), the specified URLs will be downloaded and scanned for additional
+ Eggs and archives found by way of ``--find-links`` are only downloaded if
+ they are needed to meet a requirement specified on the command line; links
+ to unneeded packages are ignored.
+ If all requested packages can be found using links on the specified
+ download pages, the Python Package Index will not be consulted unless you
+ also specified the ``--upgrade`` or ``-U`` option.
+ (Note: if you want to refer to a local HTML file containing links, you must
+ use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
+ You may specify multiple URLs or file/directory names with this option,
+ separated by whitespace. Note that on the command line, you will probably
+ have to surround the URL list with quotes, so that it is recognized as a
+ single option value. You can also specify URLs in a configuration file;
+ see `Configuration Files`_, above.
+ Changed in 0.6a10: previously all URLs and directories passed to this
+ option were scanned as early as possible, but from 0.6a10 on, only
+ directories and direct archive links are scanned immediately; URLs are not
+ retrieved unless a package search was already going to go online due to a
+ package not being available locally, or due to the use of the ``--update``
+``--delete-conflicting, -D`` (Removed in 0.6a11)
+ (As of 0.6a11, this option is no longer necessary; please do not use it!)
+ If you are replacing a package that was previously installed *without*
+ using EasyInstall, the old version may end up on ``sys.path`` before the
+ version being installed with EasyInstall. EasyInstall will normally abort
+ the installation of a package if it detects such a conflict, and ask you to
+ manually remove the conflicting files or directories. If you specify this
+ option, however, EasyInstall will attempt to delete the files or
+ directories itself, and then proceed with the installation.
+``--ignore-conflicts-at-my-risk`` (Removed in 0.6a11)
+ (As of 0.6a11, this option is no longer necessary; please do not use it!)
+ Ignore conflicting packages and proceed with installation anyway, even
+ though it means the package probably won't work properly. If the
+ conflicting package is in a directory you can't write to, this may be your
+ only option, but you will need to take more invasive measures to get the
+ installed package to work, like manually adding it to ``PYTHONPATH`` or to
+ ``sys.path`` at runtime.
+``--index-url=URL, -i URL`` (New in 0.4a1)
+ Specifies the base URL of the Python Package Index. The default is
+ http://www.python.org/pypi if not specified. When a package is requested
+ that is not locally available or linked from a ``--find-links`` download
+ page, the package index will be searched for download pages for the needed
+ package, and those download pages will be searched for links to download
+ an egg or source distribution.
+``--editable, -e`` (New in 0.6a1)
+ Only find and download source distributions for the specified projects,
+ unpacking them to subdirectories of the specified ``--build-directory``.
+ EasyInstall will not actually build or install the requested projects or
+ their dependencies; it will just find and extract them for you. See
+ `Editing and Viewing Source Packages`_ above for more details.
+``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
+ Set the directory used to build source packages. If a package is built
+ from a source distribution or checkout, it will be extracted to a
+ subdirectory of the specified directory. The subdirectory will have the
+ same name as the extracted distribution's project, but in all-lowercase.
+ If a file or directory of that name already exists in the given directory,
+ a warning will be printed to the console, and the build will take place in
+ a temporary directory instead.
+ This option is most useful in combination with the ``--editable`` option,
+ which forces EasyInstall to *only* find and extract (but not build and
+ install) source distributions. See `Editing and Viewing Source Packages`_,
+ above, for more information.
+``--verbose, -v, --quiet, -q`` (New in 0.4a4)
+ Control the level of detail of EasyInstall's progress messages. The
+ default detail level is "info", which prints information only about
+ relatively time-consuming operations like running a setup script, unpacking
+ an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the
+ detail level to "warn", which will only display installation reports,
+ warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail
+ level to include individual file-level operations, link analysis messages,
+ and distutils messages from any setup scripts that get run. If you include
+ the ``-v`` option more than once, the second and subsequent uses are passed
+ down to any setup scripts, increasing the verbosity of their reporting as
+``--dry-run, -n`` (New in 0.4a4)
+ Don't actually install the package or scripts. This option is passed down
+ to any setup scripts run, so packages should not actually build either.
+ This does *not* skip downloading, nor does it skip extracting source
+ distributions to a temporary/build directory.
+``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
+ If you are installing from a source distribution, and are *not* using the
+ ``--zip-ok`` option, this option controls the optimization level for
+ compiling installed ``.py`` files to ``.pyo`` files. It does not affect
+ the compilation of modules contained in ``.egg`` files, only those in
+ ``.egg`` directories. The optimization level can be set to 0, 1, or 2;
+ the default is 0 (unless it's set under ``install`` or ``install_lib`` in
+ one of your distutils configuration files).
+``--record=FILENAME`` (New in 0.5a4)
+ Write a record of all installed files to FILENAME. This is basically the
+ same as the same option for the standard distutils "install" command, and
+ is included for compatibility with tools that expect to pass this option
+``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1)
+ Specify one or more custom "site" directories (separated by commas).
+ "Site" directories are directories where ``.pth`` files are processed, such
+ as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall
+ automatically detects whether a given directory processes ``.pth`` files
+ (or can be made to do so), so you should not normally need to use this
+ option. It is is now only necessary if you want to override EasyInstall's
+ judgment and force an installation directory to be treated as if it
+ supported ``.pth`` files.
+ (If you want to *make* a non-``PYTHONPATH`` directory support ``.pth``
+ files, please see the `Administrator Installation`_ section below.)
+``--no-deps, -N`` (New in 0.6a6)
+ Don't install any dependencies. This is intended as a convenience for
+ tools that wrap eggs in a platform-specific packaging system. (We don't
+ recommend that you use it for anything else.)
+``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6)
+ Restrict downloading and spidering to hosts matching the specified glob
+ patterns. E.g. ``-H *.python.org`` restricts web access so that only
+ packages listed and downloadable from machines in the ``python.org``
+ domain. The glob patterns must match the *entire* user/host/port section of
+ the target URL(s). For example, ``*.python.org`` will NOT accept a URL
+ like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
+ Multiple patterns can be specified by separting them with commas. The
+ default pattern is ``*``, which matches anything.
+ In general, this option is mainly useful for blocking EasyInstall's web
+ access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
+ or other trusted site. EasyInstall will do the best it can to satisfy
+ dependencies given your host restrictions, but of course can fail if it
+ can't find suitable packages. EasyInstall displays all blocked URLs, so
+ that you can adjust your ``--allow-hosts`` setting if it is more strict
+ than you intended. Some sites may wish to define a restrictive default
+ setting for this option in their `configuration files`_, and then manually
+ override the setting on the command line as needed.
+``--prefix=DIR`` (New in 0.6a10)
+ Use the specified directory as a base for computing the default
+ installation and script directories. On Windows, the resulting default
+ directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
+ while on other platforms the defaults will be
+ ``prefix/lib/python2.X/site-packages`` (with the appropriate version
+ substituted) for libraries and ``prefix/bin`` for scripts.
+ Note that the ``--prefix`` option only sets the *default* installation and
+ script directories, and does not override the ones set on the command line
+ or in a configuration file.
+.. _non-root installation:
+Custom Installation Locations
+EasyInstall manages what packages are active using Python ``.pth`` files, which
+are normally only usable in Python's main ``site-packages`` directory. On some
+platforms (such as Mac OS X), there are additional ``site-packages``
+directories that you can use besides the main one, but usually there is only
+one directory on the system where you can install packages without extra steps.
+There are many reasons, however, why you might want to install packages
+somewhere other than the ``site-packages`` directory. For example, you might
+not have write access to that directory. You may be working with unstable
+versions of packages that you don't want to install system-wide. And so on.
+The following sections describe various approaches to custom installation; feel
+free to choose which one best suits your system and needs.
+ This approach is for when you have write access to ``site-packages`` (or
+ another directory where ``.pth`` files are processed), but don't want to
+ install packages there. This can also be used by a system administrator
+ to enable each user having their own private directories that EasyInstall
+ will use to install packages.
+`Mac OS X "User" Installation`_
+ This approach produces a result similar to an administrator installation
+ that gives each user their own private package directory, but on Mac OS X
+ the hard part has already been done for you. This is probably the best
+ approach for Mac OS X users.
+`Creating a "Virtual" Python`_
+ This approach is for when you don't have "root" or access to write to the
+ ``site-packages`` directory, and would like to be able to set up one or
+ more "virtual python" executables for your projects. This approach
+ gives you the benefits of multiple Python installations, but without having
+ to actually install Python more than once and use up lots of disk space.
+ (Only the Python executable is copied; the libraries will be symlinked
+ from the systemwide Python.)
+ If you don't already have any ``PYTHONPATH`` customization or
+ special distutils configuration, and you can't use either of the preceding
+ approaches, this is probably the best one for you.
+`"Traditional" PYTHONPATH-based Installation`_
+ If you already have a custom ``PYTHONPATH``, and/or a custom distutils
+ configuration, and don't want to change any of your existing setup, you may
+ be interested in this approach. (If you're using a custom ``.pth`` file to
+ point to your custom installation location, however, you should use
+ `Administrator Installation`_ to enable ``.pth`` processing in the custom
+ location instead, as that is easier and more flexible than this approach.)
+If you have root access to your machine, you can easily configure it to allow
+each user to have their own directory where Python packages can be installed
+and managed by EasyInstall.
+First, create an ``altinstall.pth`` file in Python's ``site-packages``
+directory, containing the following line (substituting the correct Python
+ import os, site; site.addsitedir(os.path.expanduser('~/lib/python2.3'))
+This will automatically add each user's ``~/lib/python2.X`` directory to
+``sys.path`` (if it exists), *and* it will process any ``.pth`` files in that
+directory -- which is what makes it usable with EasyInstall.
+The next step is to create or modify ``distutils.cfg`` in the ``distutils``
+directory of your Python library. The correct directory will be something like
+``/usr/lib/python2.X/distutils`` on most Posix systems and something like
+``C:\\Python2X\Lib\distutils`` on Windows machines. Add the following lines
+to the file, substituting the correct Python version if necessary::
+ install_lib = ~/lib/python2.3
+ # This next line is optional but often quite useful; it directs EasyInstall
+ # and the distutils to install scripts in the user's "bin" directory. For
+ # Mac OS X framework Python builds, you should use /usr/local/bin instead,
+ # because neither ~/bin nor the default script installation location are on
+ install_scripts = ~/bin
+This will configure the distutils and EasyInstall to install packages to the
+user's home directory by default.
+Of course, you aren't limited to using a ``~/lib/python2.X`` directory with
+this approach. You can substitute a specific systemwide directory if you like.
+You can also edit ``~/.pydistutils.cfg`` (or ``~/pydistutils.cfg`` on Windows)
+instead of changing the master ``distutils.cfg`` file. The true keys of this
+approach are simply that:
+1. any custom installation directory must be added to ``sys.path`` using a
+ ``site.addsitedir()`` call from a working ``.pth`` file or
+2. The active distutils configuration file(s) or ``easy_install`` command line
+ should include the custom directory in the ``--site-dirs`` option, so that
+ EasyInstall knows that ``.pth`` files will work in that location. (This is
+ because Python does not keep track of what directories are or aren't enabled
+ for ``.pth`` processing, in any way that EasyInstall can find out.)
+As long as both of these things have been done, your custom installation
+Mac OS X "User" Installation
+If you are on a Mac OS X machine, you should just use the
+``~/Library/Python2.x/site-packages`` directory as your custom installation
+location, because it is already configured to process ``.pth`` files, and
+EasyInstall already knows this.
+Before installing EasyInstall/setuptools, just create a ``~/.pydistutils.cfg``
+file with the following contents (or add this to the existing contents)::
+ install_lib = ~/Library/Python$py_version_short/site-packages
+ install_scripts = ~/bin
+This will tell the distutils and EasyInstall to always install packages in
+your personal ``site-packages`` directory, and scripts to ``~/bin``. (Note: do
+*not* replace ``$py_version_short`` with an actual Python version in the
+configuration file! The distutils will substitute the correct value at
+runtime, so that the above configuration file should work correctly no matter
+what Python version you use, now or in the future.)
+Once you have done this, you can follow the normal `installation instructions`_
+and use ``easy_install`` without any other special options or steps.
+(Note, however, that ``~/bin`` is not in the default ``PATH``, so you may have
+to refer to scripts by their full location. You may want to modify your shell
+startup script (likely ``.bashrc`` or ``.profile``) or your
+``~/.MacOSX/environment.plist`` to include ``~/bin`` in your ``PATH``.
+Creating a "Virtual" Python
+If you are on a Linux, BSD, Cygwin, or other similar Unix-like operating
+system, but don't have root access, you can create your own "virtual"
+Python installation, which uses its own library directories and some symlinks
+to the site-wide Python.
+In the simplest case, your virtual Python installation will live under the
+``~/lib/python2.x``, ``~/include/python2.x``, and ``~/bin`` directories. Just
+download `virtual-python.py`_ and run it using the site-wide Python. If you
+want to customize the location, you can use the ``--prefix`` option to specify
+an installation base directory in place of ``~``. (Use ``--help`` to get the
+complete list of options.)
+.. _virtual-python.py: http://peak.telecommunity.com/dist/virtual-python.py
+When you're done, you'll have a ``~/bin/python`` executable that's linked to
+the local Python installation and inherits all its current libraries, but which
+allows you to add as many new libraries as you want. Simply use this new
+Python in place of your system-defined one, and you can modify it as you like
+without breaking anything that relies on the system Python. You'll also still
+need to follow the standard `installation instructions`_ to install setuptools
+and EasyInstall, using your new ``~/bin/python`` executable in place of the
+Note that if you were previously setting a ``PYTHONPATH`` and/or had other
+special configuration options in your ``~/.pydistutils.cfg``, you may need to
+remove these settings *before* running ``virtual-python.py``. This is because
+your new Python executable will not need *any* custom configuration for the
+distutils or EasyInstall; everything will go to the correct ``~/lib`` and
+``~/bin`` directories automatically.
+You should, however, also make sure that the ``bin`` subdirectory of your
+installation prefix (e.g. ``~/bin``) is on your ``PATH``, because that is where
+EasyInstall and the distutils will install new Python scripts.
+"Traditional" ``PYTHONPATH``-based Installation
+This installation method is not as robust or as flexible as `creating a
+"virtual" python`_ installation, as it uses various tricks to fool Python into
+processing ``.pth`` files where it normally wouldn't. We suggest you at least
+consider using one of the other approaches, as they will generally result in
+a cleaner, more usable Python configuration. However, if for some reason you
+can't or won't use one of the other approaches, here's how to do it.
+Assuming that you want to install packages in a directory called ``~/py-lib``,
+and scripts in ``~/bin``, here's what you need to do:
+First, edit ``~/.pydistutils.cfg`` to include these settings, if you don't
+ install_scripts = ~/bin
+Be sure to do this *before* you try to run the ``ez_setup.py`` installation
+script. Then, follow the standard `installation instructions`_, but make
+sure that ``~/py-lib`` is listed in your ``PYTHONPATH`` environment variable.
+Your library installation directory *must* be in listed in ``PYTHONPATH``,
+not only when you install packages with EasyInstall, but also when you use
+any packages that are installed using EasyInstall. You will probably want to
+edit your ``~/.profile`` or other configuration file(s) to ensure that it is
+set, if you haven't already got this set up on your machine.
+Release Notes/Change History
+ * Added automatic retry for Sourceforge mirrors. The new download process is
+ to first just try dl.sourceforge.net, then randomly select mirror IPs and
+ remove ones that fail, until something works. The removed IPs stay removed
+ for the remainder of the run.
+ * Process ``dependency_links.txt`` if found in a distribution, by adding the
+ URLs to the list for scanning.
+ * Use relative paths in ``.pth`` files when eggs are being installed to the
+ same directory as the ``.pth`` file. This maximizes portability of the
+ target directory when building applications that contain eggs.
+ * Added ``easy_install-N.N`` script(s) for convenience when using multiple
+ * Added automatic handling of installation conflicts. Eggs are now shifted to
+ the front of sys.path, in an order consistent with where they came from,
+ making EasyInstall seamlessly co-operate with system package managers.
+ The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options
+ are now no longer necessary, and will generate warnings at the end of a
+ * Don't recursively traverse subdirectories given to ``--find-links``.
+ * Added exhaustive testing of the install directory, including a spawn test
+ for ``.pth`` file support, and directory writability/existence checks. This
+ should virtually eliminate the need to set or configure ``--site-dirs``.
+ * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of
+ * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it
+ manually to make it work. ``--multi-version`` is no longer a silent
+ default; you must explicitly use it if installing to a non-PYTHONPATH,
+ * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``,
+ ``--install-dir``, and ``--script-dir`` options, whether on the command line
+ or in configuration files.
+ * Improved SourceForge mirror processing to work faster and be less affected
+ by transient HTML changes made by SourceForge.
+ * PyPI searches now use the exact spelling of requirements specified on the
+ command line or in a project's ``install_requires``. Previously, a
+ normalized form of the name was used, which could lead to unnecessary
+ full-index searches when a project's name had an underscore (``_``) in it.
+ * EasyInstall can now download bare ``.py`` files and wrap them in an egg,
+ as long as you include an ``#egg=name-version`` suffix on the URL, or if
+ the ``.py`` file is listed as the "Download URL" on the project's PyPI page.
+ This allows third parties to "package" trivial Python modules just by
+ linking to them (e.g. from within their own PyPI page or download links
+ * The ``--always-copy`` option now skips "system" and "development" eggs since
+ they can't be reliably copied. Note that this may cause EasyInstall to
+ choose an older version of a package than what you expected, or it may cause
+ downloading and installation of a fresh version of what's already installed.
+ * The ``--find-links`` option previously scanned all supplied URLs and
+ directories as early as possible, but now only directories and direct
+ archive links are scanned immediately. URLs are not retrieved unless a
+ package search was already going to go online due to a package not being
+ available locally, or due to the use of the ``--update`` or ``-U`` option.
+ * Fixed the annoying ``--help-commands`` wart.
+ * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside
+ "baskets") when they weren't explicitly listed in the ``.pth`` file.
+ * If more than one URL appears to describe the exact same distribution, prefer
+ the shortest one. This helps to avoid "table of contents" CGI URLs like the
+ * Quote arguments to python.exe (including python's path) to avoid problems
+ when Python (or a script) is installed in a directory whose name contains
+ * 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.
+ * Update for changed SourceForge mirror format
+ * Fixed not installing dependencies for some packages fetched via Subversion
+ * Fixed dependency installation with ``--always-copy`` not using the same
+ dependency resolution procedure as other operations.
+ * Fixed not fully removing temporary directories on Windows, if a Subversion
+ checkout left read-only files behind
+ * Fixed some problems building extensions when Pyrex was installed, especially
+ with Python 2.4 and/or packages using SWIG.
+ * Fixed not being able to install Windows script wrappers using Python 2.3
+ * Added support for "traditional" PYTHONPATH-based non-root installation, and
+ also the convenient ``virtual-python.py`` script, based on a contribution
+ by Ian Bicking. The setuptools egg now contains a hacked ``site`` module
+ that makes the PYTHONPATH-based approach work with .pth files, so that you
+ can get the full EasyInstall feature set on such installations.
+ * Added ``--no-deps`` and ``--allow-hosts`` options.
+ * Improved Windows ``.exe`` script wrappers so that the script can have the
+ same name as a module without confusing Python.
+ * Changed dependency processing so that it's breadth-first, allowing a
+ depender's preferences to override those of a dependee, to prevent conflicts
+ when a lower version is acceptable to the dependee, but not the depender.
+ Also, ensure that currently installed/selected packages aren't given
+ precedence over ones desired by a package being installed, which could
+ * Improved error message when trying to use old ways of running
+ ``easy_install``. Removed the ability to run via ``python -m`` or by
+ running ``easy_install.py``; ``easy_install`` is the command to run on all
+ * Improved wrapper script generation and runtime initialization so that a
+ VersionConflict doesn't occur if you later install a competing version of a
+ needed package as the default version of that package.
+ * Fixed a problem parsing version numbers in ``#egg=`` links.
+ * EasyInstall can now install "console_scripts" defined by packages that use
+ ``setuptools`` and define appropriate entry points. On Windows, console
+ scripts get an ``.exe`` wrapper so you can just type their name. On other
+ platforms, the scripts are installed without a file extension.
+ * Using ``python -m easy_install`` or running ``easy_install.py`` is now
+ DEPRECATED, since an ``easy_install`` wrapper is now available on all
+ * EasyInstall now does MD5 validation of downloads from PyPI, or from any link
+ that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest.
+ * EasyInstall now handles symlinks in target directories by removing the link,
+ rather than attempting to overwrite the link's destination. This makes it
+ easier to set up an alternate Python "home" directory (as described above in
+ the `Non-Root Installation`_ section).
+ * Added support for handling MacOS platform information in ``.egg`` filenames,
+ based on a contribution by Kevin Dangoor. You may wish to delete and
+ reinstall any eggs whose filename includes "darwin" and "Power_Macintosh",
+ because the format for this platform information has changed so that minor
+ OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
+ previous OS version to become obsolete.
+ * easy_install's dependency processing algorithms have changed. When using
+ ``--always-copy``, it now ensures that dependencies are copied too. When
+ not using ``--always-copy``, it tries to use a single resolution loop,
+ * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
+ * Added ``--site-dirs`` option to allow adding custom "site" directories.
+ Made ``easy-install.pth`` work in platform-specific alternate site
+ directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X).
+ * If you manually delete the current version of a package, the next run of
+ EasyInstall against the target directory will now remove the stray entry
+ from the ``easy-install.pth`` file.
+ * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID
+ as pointing to the named project's source checkout. Such URLs have a lower
+ match precedence than any other kind of distribution, so they'll only be
+ used if they have a higher version number than any other available
+ distribution, or if you use the ``--editable`` option. The ``#egg``
+ fragment can contain a version if it's formatted as ``#egg=proj-ver``,
+ where ``proj`` is the project name, and ``ver`` is the version number. You
+ *must* use the format for these values that the ``bdist_egg`` command uses;
+ i.e., all non-alphanumeric runs must be condensed to single underscore
+ * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_
+ above for more info. Also, slightly changed the behavior of the
+ ``--build-directory`` option.
+ * Fixed the setup script sandbox facility not recognizing certain paths as
+ valid on case-insensitive platforms.
+ * Fix ``python -m easy_install`` not working due to setuptools being installed
+ as a zipfile. Update safety scanner to check for modules that might be used
+ as ``python -m`` scripts.
+ * Misc. fixes for win32.exe support, including changes to support Python 2.4's
+ changed ``bdist_wininst`` format.
+ * Put the ``easy_install`` module back in as a module, as it's needed for
+ ``python -m`` to run it!
+ * Allow ``--find-links/-f`` to accept local directories or filenames as well
+ * EasyInstall now automatically detects when an "unmanaged" package or
+ module is going to be on ``sys.path`` ahead of a package you're installing,
+ thereby preventing the newer version from being imported. By default, it
+ will abort installation to alert you of the problem, but there are also
+ new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``)
+ available to change the default behavior. (Note: this new feature doesn't
+ take effect for egg files that were built with older ``setuptools``
+ versions, because they lack the new metadata file required to implement it.)
+ * The ``easy_install`` distutils command now uses ``DistutilsError`` as its
+ base error type for errors that should just issue a message to stderr and
+ exit the program without a traceback.
+ * EasyInstall can now be given a path to a directory containing a setup
+ script, and it will attempt to build and install the package there.
+ * EasyInstall now performs a safety analysis on module contents to determine
+ whether a package is likely to run in zipped form, and displays
+ information about what modules may be doing introspection that would break
+ when running as a zipfile.
+ * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that
+ would ordinarily be considered safe to unzip, and changed the meaning of
+ ``--zip-ok/-z`` to "always leave everything zipped".
+ * There is now a separate documentation page for `setuptools`_; revision
+ history that's not specific to EasyInstall has been moved to that page.
+ .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+ * 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
+ * Added ``--always-copy/-a`` option to always copy needed packages to the
+ installation directory, even if they're already present elsewhere on
+ sys.path. (In previous versions, this was the default behavior, but now
+ * Added ``--upgrade/-U`` option to force checking PyPI for latest available
+ version(s) of all packages requested by name and version, even if a matching
+ version is available locally.
+ * Added automatic installation of dependencies declared by a distribution
+ being installed. These dependencies must be listed in the distribution's
+ ``EGG-INFO`` directory, so the distribution has to have declared its
+ dependencies by using setuptools. If a package has requirements it didn't
+ declare, you'll still have to deal with them yourself. (E.g., by asking
+ EasyInstall to find and install them.)
+ * Added the ``--record`` option to ``easy_install`` for the benefit of tools
+ that run ``setup.py install --record=filename`` on behalf of another
+ * Fixed not setting script permissions to allow execution.
+ * Improved sandboxing so that setup scripts that want a temporary directory
+ (e.g. pychecker) can still run in the sandbox.
+ * Fix stupid stupid refactoring-at-the-last-minute typos. :(
+ * Added support for converting ``.win32.exe`` installers to eggs on the fly.
+ EasyInstall will now recognize such files by name and install them.
+ * Fixed a problem with picking the "best" version to install (versions were
+ being sorted as strings, rather than as parsed values)
+ * Added support for the distutils "verbose/quiet" and "dry-run" options, as
+ well as the "optimize" flag.
+ * Support downloading packages that were uploaded to PyPI (by scanning all
+ links on package pages, not just the homepage/download links).
+ * Add progress messages to the search/download process so that you can tell
+ what URLs it's reading to find download links. (Hopefully, this will help
+ people report out-of-date and broken links to package authors, and to tell
+ when they've asked for a package that doesn't exist.)
+ * Added support for installing scripts
+ * Added support for setting options via distutils configuration files, and
+ using distutils' default options as a basis for EasyInstall's defaults.
+ * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the
+ script installation directory option.
+ * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
+ Python includes SSL support.
+ * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
+ and search PyPI for needed packages.
+ * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
+ URL installs, to avoid running the wrong setup.py.
+ * Added ``--build-directory=DIR/-b DIR`` option.
+ * Added "installation report" that explains how to use 'require()' when doing
+ a multiversion install or alternate installation directory.
+ * Added SourceForge mirror auto-select (Contributed by Ian Bicking)
+ * Added "sandboxing" that stops a setup script from running if it attempts to
+ write to the filesystem outside of the build area
+ * Added more workarounds for packages with quirky ``install_data`` hacks
+ * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
+ automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)
+* Additional utilities to list/remove/verify packages
+* Signature checking? SSL? Ability to suppress PyPI search?
+* Display byte progress meter when downloading distributions and long pages?
+* Redirect stdout/stderr to log during run_setup?