|The PEAK Developers' Center||FrontPage||RecentChanges||TitleIndex||WordIndex||SiteNavigation||HelpContents|
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!)
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 easy_install http://peak.telecommunity.com/dist/setuptools-0.4a1-py2.3.egg # Python 2.4 easy_install http://peak.telecommunity.com/dist/setuptools-0.4a1-py2.4.egg
For basic use of easy_install, you need only supply the filename or URL of a source distribution or .egg file (Python Egg).
Example 1. Install a package by name, searching PyPI for the latest version, and automatically downloading, building, and installing it:
Example 2. Install a package by name and version from a given "download page":
easy_install -s http://peak.telecommunity.com/dist "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 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.
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.:
a version greater than the one you have now:
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.
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.
If you've upgraded a package, but need to revert to a previously-installed version, you can do so like this:
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:
This will activate the latest installed version.
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.
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" 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
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.
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 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.
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.