path: root/EasyInstall.txt

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

Easy Install is a python module (``easy_install``) 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!)

.. contents:: **Table of Contents**


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


Installing "Easy Install"
-------------------------

Windows users can just download and run the `setuptools binary installer for
Windows <http://peak.telecommunity.com/dist/setuptools-0.4a4.win32.exe>`_.
All others should just download `ez_setup.py
<http://peak.telecommunity.com/dist/ez_setup.py>`_, and run it; this will
download and install the correct version of ``setuptools`` for your Python
version.  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``.
    
An ``easy_install.py`` script will be installed in the normal location for
Python scripts on your platform. In the examples below, you'll need to replace
references to ``easy_install`` with the correct invocation to run
``easy_install.py`` on your system. If you have Python 2.4 or better, you can
also use ``python -m easy_install``, which will have the same effect, but which
may be easier for you to type.

(Note: 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.  However, you should avoid using a custom installation
directory or doing multi-version installs of the setuptools package, because
this may make it impossible for scripts installed with EasyInstall to access
it afterwards.)


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://peak.telecommunity.com/dist "setuptools>=0.4a4"

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

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* (not binary) distribution files with extensions of .tgz,
.tar, .tar.gz, .tar.bz2, or .zip.  And of course it handles already-built .egg
distributions as well.

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"

or by using a download page, direct download URL, or package filename::

    easy_install -s 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``), the ``require()`` function automatically selects the newest
available version of a package that meets your version criteria at runtime, so
installation is the only step needed.

If you're installing to ``site-packages`` 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.

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.


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``
    Enable installing the package as a zip file. This can significantly
    increase Python's overall import performance if you're installing to
    ``site-packages`` and not using the ``--multi`` option, because Python
    process zipfile entries on ``sys.path`` much faster than it does
    directories. So, if you don't use this option, and you install a lot of
    packages, some of them may be slower to import.

    But, this option is disabled by default, unless you're installing from an
    already-built binary zipfile (``.egg`` file). This is to avoid problems
    when using packages that dosn't support running from a zip file. Such
    packages usually access data files in their package directories using the
    Python ``__file__`` or ``__path__`` attribute, instead of the
    ``pkg_resources`` API. So, if you find that a package doesn't work properly
    when used with this option, you may want to suggest to the author that they
    switch to using the ``pkg_resources`` resource API, which will allow their
    package to work whether it's installed as a zipfile or not.

    (Note: this option only affects the installation of newly-built 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.)

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

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

``--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 ``file:`` URLs to reference a local filename.

    You may specify multiple URLs with this option, separated by whitespace.
    Note that on the command line, you will probably have to surround the URLs
    with quotes, so that they are 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.

``--index-url=URL, -u 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.

``--build-directory=DIR, -b DIR`` (New in 0.3a3)
    Set the directory used to download, extract, and install the package.  The
    directory is not cleared before or after installation, so the downloaded
    packages and extracted contents will remain there afterwards, allowing you
    to read any documentation, examples, scripts, etc. that may have been
    included with the source distribution (if any).

    This option can only be used when you are specifying a single installation
    URL or filename, so that the installer will not be confused by the presence
    of multiple ``setup.py`` files in the build directory.

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


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

 * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource
   directory extraction for zipped eggs.

0.4a3
 * Fixed scripts not being able to see a ``__file__`` variable in ``__main__``

 * Fixed a problem with ``resource_isdir()`` implementation that was introduced
   in 0.4a2.

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

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

 * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
   Python includes SSL support.

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

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

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

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

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

 * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and
   ``!=``) when only one condition was included.

 * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of
   arbitrary distribution names and versions found on PyPI.

0.3a4
 * ``pkg_resources`` now supports resource directories, not just the resources
   in them.  In particular, there are ``resource_listdir()`` and
   ``resource_isdir()`` APIs.

 * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain
   multiple distributions in subdirectories whose names end with ``.egg``.
   Having such a "basket" in a directory on ``sys.path`` is equivalent to
   having the individual eggs in that directory, but the contained eggs can
   be individually added (or not) to ``sys.path``.  Currently, however, there
   is no automated way to create baskets.

 * Namespace package manipulation is now protected by the Python import lock.

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

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

 * Misc. bug fixes

0.3a1
 Initial release.


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

* Process the installed package's dependencies as well as the base package
* Support "self-installation" - bootstrapping setuptools install into another
  package's installation process (copy egg, write setuptools.pth)
* Support installation from bdist_wininst packages?
* 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?