============
Easy Install
============

Easy Install is a python module (``easy_install``) bundled with ``setuptools``
that lets you automatically download, build, install, and manage Python
packages.

(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**


Using "Easy Install"
====================


.. _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.

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
  installing.

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.


Troubleshooting
~~~~~~~~~~~~~~~

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.


Windows Notes
~~~~~~~~~~~~~

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
directory to it.

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`__).

__ http://peak.telecommunity.com/DevCenter/PythonEggs

**Example 1**. Install a package by name, searching PyPI for the latest
version, and automatically downloading, building, and installing it::

    easy_install SQLObject

**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
listed on PyPI::

    easy_install --upgrade PyProtocols

**Example 6**.  Install a source distribution that's already downloaded and
extracted in the current directory (New in 0.5a9)::

    easy_install .

**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``
option.

Packages installed to ``site-packages`` are added to an ``easy-install.pth``
file, 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.

Note, however, that installing to a directory other than ``site-packages``
already implies the ``-m`` option, so if you cannot install to
``site-packages``, please see the `Command-Line Options`_ section below (under
``--multi-version``) to find out how to select packages at runtime.


Upgrading a Package
-------------------

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`` (or installing outside of
``site-packages``), 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 Python's ``site-packages`` 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 not installing to ``site-packages``.

``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
Packages`_, below.


Changing the Active Version (``site-packages`` installs only)
-------------------------------------------------------------

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
can do so like this::

    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
specified.


Uninstalling Packages
---------------------

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.


Managing Scripts
----------------

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.)


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::

    [build]
    compiler = mingw32

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
downloaded package.

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 \
     ctypes==0.9.6


Dealing with Installation Conflicts
-----------------------------------

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
about!


Compressed Installation
-----------------------

EasyInstall tries to install packages in zipped form, if it can.  Zipping
packages can significantly increase Python's overall import performance if
you're installing to``site-packages`` and not using the ``--multi`` 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
``--zip-ok`` option.)

The current analysis approach is very 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
   environments)

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.)


Reference Manual
================

Configuration Files
-------------------

(New in 0.4a2)

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::

    [easy_install]

    # 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/
                 http://peak.telecommunity.com/dist/

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>`_.


Command-Line Options
--------------------

``--zip-ok, -z``
    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.)

``--always-unzip, -Z``
    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, -m``
    "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
    simple 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
    doc.)

    Note that if you install to a directory other than ``site-packages``,
    this option is automatically in effect, because ``.pth`` files can only be
    used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
    the ``--install-dir`` or ``-d`` option (or they are set via configuration
    file(s)) you must also use ``require()`` to enable packages at runtime.

``--upgrade, -U``   (New in 0.5a4)
    By default, EasyInstall only searches the Python Package Index 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 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
    need.

    (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.

``--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.

``--exclude-scripts, -x``
    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.

``--find-links=URL, -f URL`` (Option renamed in 0.4a2)
    Scan the specified "download pages" for direct links to downloadable eggs
    or source distributions.  Any usable packages will be downloaded if they
    are required by a command line argument.  For example, this::

        easy_install -f http://peak.telecommunity.com/dist PyProtocols

    will download and install the latest version of PyProtocols linked from
    the PEAK downloads page, but ignore the other download links on that page.
    If all requested packages can be found using links on the specified
    download pages, the Python Package Index will *not* be consulted.  You can
    use a ``file:`` URL to reference a local HTML file containing links, or you
    can just use the name of a directory containing "distribution files"
    (source archives, eggs, Windows installers, etc.), and EasyInstall will
    then be aware of the files available there.

    You may specify multiple URLs or directories 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; but note that this means the specified pages
    will be downloaded every time you use EasyInstall (unless overridden on the
    command line) and thus may make startup slower.

``--delete-conflicting, -D`` (New in 0.5a9)
    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`` (New in 0.5a9)
    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
    well.

``--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
    to "setup.py install".

``--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. By default, EasyInstall
    only knows about Python-defined "site" directories, not those that may be
    added by an OS distribution or site administrator using call(s) to
    ``site.addsitedir()``.  You should not normally need to use this option
    directly, as your system administrator should configure it in the
    ``distutils.cfg`` file of the Python installation.  See the `Administrator
    Installation`_ section below for details.

``--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.


.. _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.

`Administrator Installation`_
    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.)

    This is the least robust and least flexible of the approaches, however, so
    you should probably at least take a look at the others and consider whether
    one of them might be an improvement over your current setup.


Administrator Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~

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
version)::

    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]
    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
    # the system PATH.
    #
    install_scripts = ~/bin

    [easy_install]
    site_dirs = ~/lib/python2.3

This will configure the distutils and EasyInstall to install packages to the
user's home directory by default, and will tell EasyInstall that Python has
been configured to accept ``.pth`` files in that directory.

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
   ``sitecustomize.py``.

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
location is good to go.


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]
    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
system Python.

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
already have them::

    [install]
    install_lib = ~/py-lib
    install_scripts = ~/bin
    
    [easy_install]
    site_dirs = ~/py_lib

Be sure to do this *before* you try to run the ``ez_setup.py`` installation
script.  Then, follow the standard `installation instructions`_, but take
careful note of the full pathname of the ``.egg`` file that gets installed, so
that you can add it to your ``PYTHONPATH``, along with ``~/py_lib``.

You *must* add the setuptools egg file *and* ``~/py_lib`` to your
``PYTHONPATH`` environment variable manually, or it will not work, and neither
will any other packages you install with EasyInstall.  You will not, however,
have to manually add any other packages to the ``PYTHONPATH``; EasyInstall will
take care of them for you by automatically editing
``~/py-lib/easy-install.pth``, as long as the setuptools egg is explicitly
listed in ``PYTHONPATH``.


Release Notes/Change History
============================

Known Issues
 * There's no automatic retry for borked Sourceforge mirrors, which can easily
   time out or be missing a file.

0.6a9

 * 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
   ones on effbot.org.

 * 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
   spaces on Windows.

 * 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.

0.6a8
 * 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.

0.6a7
 * Fixed not being able to install Windows script wrappers using Python 2.3

0.6a6
 * 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
   cause conflict errors.

0.6a3
 * 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
   supported platforms.

 * 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.
   
0.6a2
 * 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
   platforms.

0.6a1
 * 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,
   rather than recursing.

 * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
   extensions.

 * 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
   characters.

 * 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.

0.5a12
 * 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.

0.5a10
 * 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
   as URLs.

0.5a9
 * 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".

0.5a8
 * 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

0.5a5
 * 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.

0.5a4
 * 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
   you must request it.)

 * 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
   packaging system.)

0.5a3
 * 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.

0.5a2
 * Fix stupid stupid refactoring-at-the-last-minute typos.  :(

0.5a1
 * 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)

0.4a4
 * 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).

0.4a3
 * 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.)

0.4a2
 * 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.

0.4a1
 * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
   and search PyPI for needed packages.

0.3a4
 * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
   URL installs, to avoid running the wrong setup.py.

0.3a3
 * 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

0.3a2
 * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
   automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)

 * Misc. bug fixes

0.3a1
 * Initial release.


Future Plans
============

* 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?

