The PEAK Developers' Center   EasyInstall UserPreferences
HelpContents Search Diffs Info Edit Subscribe XML Print View
Version as of 2005-06-14 22:26:56

Clear message

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 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 page. Thanks!)

Table of Contents

Using "Easy Install"

Installing "Easy Install"

Windows users can just download and run the setuptools binary installer for Windows. All others should just download, 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 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 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 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).

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 "setuptools>=0.5a1"

Example 3. Download a source distribution from a specified URL, automatically building and installing it:


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

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

easy_install -s ExamplePackage


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 package. You might first install one version:

easy_install -m docutils==0.3.9

then rename the to r2h_039, and install another version:

easy_install -m docutils==0.3.10

This will create another 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:

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:


# 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 =

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.

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 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 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 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.
  • Added support for converting .win32.exe installers to eggs on the fly. EasyInstall will now recognize such files by name and install them.

  • Added support for "self-installation" bootstrapping. Packages can now include in their source distribution, and add the following to their, in order to automatically bootstrap installation of setuptools as part of their setup process:

    from ez_setup import use_setuptools
    from setuptools import setup
    # etc...
  • 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).
  • Fix problems with resource_listdir(), resource_isdir() and resource directory extraction for zipped eggs.
  • 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.)
  • 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 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.
  • 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.
  • 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
  • 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)
  • 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 bdist_egg --help to get more information.
  • Misc. bug fixes
Initial release.

Future Plans

EditText of this page (last modified 2005-06-14 22:26:56)
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck