The PEAK Developers' Center   EasyInstall UserPreferences
HelpContents Search Diffs Info Edit Subscribe XML Print View
Version as of 2005-06-05 17:58:55

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"

Unix-like Systems (including Mac OS X and Cygwin)

Download either the Python 2.3 easy_install shell script or the Python 2.4 easy_install shell script. Place the file somewhere on your PATH, after renaming it to easy_install. Note that these scripts assume you have python2.3 or python2.4 accessible via the PATH environment variable. Then, you can use easy_install to finish its own installation, by running one of the following, depending on your Python version:

# Python 2.3

# Python 2.4
All Other Systems
Download the easy_install (aka setuptools) source distribution, and follow the normal procedure for installing a source package with distutils. 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.

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 a package by name and version from a given "download page":

easy_install -s "setuptools>=0.4a1"

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

Packages installed to site-packages are added to an easy-install.pth file, so that Python will be able to import the package by default. If you do not want this to happen, you should use the -m or --multi option, which allows multiple versions of the same package to be selected at runtime.

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

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. Note that the named package and version must already have been installed to site-packages.

If you'd like to switch to the latest version of PackageName, you can do so like this:

easy_install PackageName

This will activate the latest installed version.

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.

Reference Manual

Command-Line Options

--zip, -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 -i options, 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.
--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.

--scan-url=URL, -s URL (New in 0.4a1)

Scan the specified "download page" 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 -s 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.

You may use this option more than once, to list multiple download pages. If all requested packages can be found using the specified download pages, the Python Package Index will not be consulted.

--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 --scan-url 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.

Release Notes/Change History

  • 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-05 17:58:55)
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck