|
| EasyInstall |
UserPreferences |
| The PEAK Developers' Center | FrontPage | RecentChanges | TitleIndex | WordIndex | SiteNavigation | HelpContents |
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! If you encounter difficulty installing a package, please contact us via the distutils mailing list. (Note: please DO NOT send private email directly to the author of setuptools; it will be discarded. The mailing list is a searchable archive of previously-asked and answered questions; you should begin your research there before reporting something as a bug -- and then do so via list discussion first.)
(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.)
Please see the setuptools PyPI page for download links and basic installation instructions for each of the supported platforms.
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.
Note that the instructions on the setuptools PyPI page assume that you are are installling to Python's primary site-packages directory. If this is not the case, you should consult the section below on Custom Installation Locations before installing. (And, on Windows, you should not use the .exe installer when installing to an alternate location.)
Note that easy_install normally works by downloading files from the internet. 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, which lets you get past such firewalls in the same way that your web browser(s) do.
(Alternately, if you do not wish easy_install to actually download anything, you can restrict it from doing so with the --allow-hosts option; see the sections on restricting downloads with --allow-hosts and command-line options for more details.)
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.
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.
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 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.
Installed packages are added to an easy-install.pth file in the install directory, 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.
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-version , 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 a directory on PYTHONPATH, or a configured "site" 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 they are installed in multi-version mode.
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:
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.
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 -mxN 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.
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 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.)
As of version 0.6a11, EasyInstall installs itself under two names: easy_install and easy_install-N.N, where N.N is the Python version used to install it. Thus, if you install EasyInstall for both Python 2.3 and 2.4, you can use the easy_install-2.3 or easy_install-2.4 scripts to install packages for Python 2.3 or 2.4, respectively.
Also, if you're working with Python version 2.4 or higher, you can run Python with -m easy_install to run that particular Python version's easy_install command.
You can use the --allow-hosts (-H) option to restrict what domains EasyInstall will look for links and downloads on. --allow-hosts=None prevents downloading altogether. You can also use wildcards, for example to restrict downloading to hosts in your own intranet. See the section below on Command-Line Options for more details on the --allow-hosts option.
By default, there are no host restrictions in effect, but you can change this default by editing the appropriate configuration files and adding:
[easy_install] allow_hosts = *.myintranet.example.com,*.python.org
The above example would then allow downloads only from hosts in the python.org and myintranet.example.com domains, unless overridden on the command line.
Just copy the eggs or source packages you need to a directory on the target machine, then use the -f or --find-links option to specify that directory's location. For example:
easy_install -H None -f somedir SomePackage
will attempt to install SomePackage using only eggs and source packages found in somedir and disallowing all remote access. You should of course make sure you have all of SomePackage's dependencies available in somedir.
If you have another machine of the same operating system and library versions (or if the packages aren't platform-specific), you can create the directory of eggs using a command like this:
easy_install -zmaxd somedir SomePackage
This will tell EasyInstall to put zipped eggs or source packages for SomePackage and all its dependencies into somedir, without creating any scripts or .pth files. You can then copy the contents of somedir to the target machine. (-z means zipped eggs, -m means multi-version, which prevents .pth files from being used, -a means to copy all the eggs needed, even if they're installed elsewhere on the machine, and -d indicates the directory to place the eggs in.)
You can also build the eggs from local development packages that were installed with the setup.py develop command, by including the -l option, e.g.:
easy_install -zmaxld somedir SomePackage
This will use locally-available source distributions to build the eggs.
Need to distribute a package that isn't published in egg form? You can use EasyInstall to build eggs for a project. You'll want to use the --zip-ok, --exclude-scripts, and possibly --no-deps options (-z, -x and -N, respectively). Use -d or --install-dir to specify the location where you'd like the eggs placed. By placing them in a directory that is published to the web, you can then make the eggs available for download, either in an intranet or to the internet at large.
If someone distributes a package in the form of a single .py file, you can wrap it in an egg by tacking an #egg=name-version suffix on the file's URL. So, something like this:
easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
will install the package as an egg, and this:
easy_install -zmaxd. \
-f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
will create a .egg file in the current directory.
In addition to local directories and the Python Package Index, EasyInstall can find download links on most any web page whose URL is given to the -f (--find-links) option. In the simplest case, you can simply have a web page with links to eggs or Python source packages, even an automatically generated directory listing (such as the Apache web server provides).
If you are setting up an intranet site for package downloads, you may want to configure the target machines to use your download site by default, adding something like this to their configuration files:
[easy_install]
find_links = http://mypackages.example.com/somedir/
http://turbogears.org/download/
http://peak.telecommunity.com/dist/
As you can see, you can list multiple URLs separated by whitespace, continuing on multiple lines if necessary (as long as the subsequent lines are indented.
If you are more ambitious, you can also create an entirely custom package index or PyPI mirror. See the --index-url option under Command-Line Options, below, and also the section on the Package Index "API".
If a site you want to download from is password-protected using HTTP "Basic" authentication, you can specify your credentials in the URL, like so:
http://some_userid:some_password@some.example.com/some_path/
You can do this with both index page URLs and direct download URLs. As long as any HTML pages read by easy_install use relative links to point to the downloads, the same user ID and password will be used to do the downloading.
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.
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
(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that people using older versions of EasyInstall can consult it. As of version 0.6a11, installation conflicts are handled automatically without deleting the old or system-installed packages, and without ignoring the issue. Instead, eggs are automatically shifted to the front of sys.path using special code added to the easy-install.pth file. So, if you are using version 0.6a11 or better of setuptools, you do not need to worry about conflicts, and the following issues do not apply to you.)
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!
EasyInstall tries to install packages in zipped form, if it can. Zipping packages can improve Python's overall import performance if you're not using the --multi-version 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 fairly 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())
- Top-level modules that might be scripts used with python -m (Python 2.4)
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.)
(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.
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" 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.)
Changed in 0.6a10: this option is no longer silently enabled when installing to a non-PYTHONPATH, non-"site" directory. You must always explicitly use this option if you want it to be active.
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, as is the --prefix option.
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.
Note that as of 0.6a10, using this option excludes "system" and "development" eggs from consideration because they can't be reliably copied. This may cause EasyInstall to choose an older version of a package than what you expected, or it may cause downloading and installation of a fresh copy of something that's already installed. You will see warning messages for any eggs that EasyInstall skips, before it falls back to an older version or attempts to download a fresh copy.
Scan the specified "download pages" or directories for direct links to eggs or other distributions. Any existing file or directory names or direct download URLs are immediately added to EasyInstall's search cache, and any indirect URLs (ones that don't point to eggs or other recognized archive formats) are added to a list of additional places to search for download links. As soon as EasyInstall has to go online to find a package (either because it doesn't exist locally, or because --upgrade or -U was used), the specified URLs will be downloaded and scanned for additional direct links.
Eggs and archives found by way of --find-links are only downloaded if they are needed to meet a requirement specified on the command line; links to unneeded packages are ignored.
If all requested packages can be found using links on the specified download pages, the Python Package Index will not be consulted unless you also specified the --upgrade or -U option.
(Note: if you want to refer to a local HTML file containing links, you must use a file: URL, as filenames that do not refer to a directory, egg, or archive are ignored.)
You may specify multiple URLs or file/directory names 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.
Changed in 0.6a10: previously all URLs and directories passed to this option were scanned as early as possible, but from 0.6a10 on, only directories and direct archive links are scanned immediately; URLs are not retrieved unless a package search was already going to go online due to a package not being available locally, or due to the use of the --update or -U option.
(As of 0.6a11, this option is no longer necessary; please do not use it!)
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.
(As of 0.6a11, this option is no longer necessary; please do not use it!)
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.
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.
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. As of 0.6a10, EasyInstall automatically detects whether a given directory processes .pth files (or can be made to do so), so you should not normally need to use this option. It is is now only necessary if you want to override EasyInstall's judgment and force an installation directory to be treated as if it supported .pth files.
(If you want to make a non-PYTHONPATH directory support .pth files, please see the Administrator Installation section below.)
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.
Use the specified directory as a base for computing the default installation and script directories. On Windows, the resulting default directories will be prefix\\Lib\\site-packages and prefix\\Scripts, while on other platforms the defaults will be prefix/lib/python2.X/site-packages (with the appropriate version substituted) for libraries and prefix/bin for scripts.
Note that the --prefix option only sets the default installation and script directories, and does not override the ones set on the command line or in a configuration file.
Normally, EasyInstall prefers to only install released versions of projects, not in-development ones, because such projects may not have a currently-valid version number. So, it usually only installs them when their setup.py directory is explicitly passed on the command line.
However, if this option is used, then any in-development projects that were installed using the setup.py develop command, will be used to build eggs, effectively upgrading the "in-development" project to a snapshot release. Normally, this option is used only in conjunction with the --always-copy option to create a distributable snapshot of every egg needed to run an application.
Note that if you use this option, you must make sure that there is a valid version number (such as an SVN revision number tag) for any in-development projects that may be used, as otherwise EasyInstall may not be able to tell what version of the project is "newer" when future installations or upgrades are attempted.
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.
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.
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
This will configure the distutils and EasyInstall to install packages to the user's home directory by default.
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:
As long as both of these things have been done, your custom installation location is good to go.
If you are on a Mac OS X machine, you should just use the ~/Library/Python/2.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.
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.)
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.
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
Be sure to do this before you try to run the ez_setup.py installation script. Then, follow the standard installation instructions, but make sure that ~/py-lib is listed in your PYTHONPATH environment variable.
Your library installation directory must be in listed in PYTHONPATH, not only when you install packages with EasyInstall, but also when you use any packages that are installed using EasyInstall. You will probably want to edit your ~/.profile or other configuration file(s) to ensure that it is set, if you haven't already got this set up on your machine.
Custom package indexes (and PyPI) must follow the following rules for EasyInstall to be able to look up and download packages:
Except where stated otherwise, "pages" are HTML or XHTML, and "links" refer to href attributes.
Individual project version pages' URLs must be of the form base/projectname/version, where base is the package index's base URL.
Omitting the /version part of a project page's URL (but keeping the trailing /) should result in a page that is either:
Individual project version pages should contain direct links to downloadable distributions where possible. It is explicitly permitted for a project's "long_description" to include URLs, and these should be formatted as HTML links by the package index, as EasyInstall does no special processing to identify what parts of a page are index-specific and which are part of the project's supplied description.
Where available, MD5 information should be added to download URLs by appending a fragment identifier of the form #md5=..., where ... is the 32-character hex MD5 digest. EasyInstall will verify that the downloaded file's MD5 digest matches the given value.
Individual project version pages should identify any "homepage" or "download" URLs using rel="homepage" and rel="download" attributes on the HTML elements linking to those URLs. Use of these attributes will cause EasyInstall to always follow the provided links, unless it can be determined by inspection that they are downloadable distributions. If the links are not to downloadable distributions, they are retrieved, and if they are HTML, they are scanned for download links. They are not scanned for additional "homepage" or "download" links, as these are only processed for pages that are part of a package index site.
The root URL of the index, if retrieved with a trailing /, must result in a page containing links to all projects' active version pages.
(Note: This requirement is a workaround for the absence of case-insensitive safe_name() matching of project names in URL paths. If project names are matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar mechanism), then it is not necessary to include this all-packages listing page.)
If a package index is accessed via a file:// URL, then EasyInstall will automatically use index.html files, if present, when trying to read a directory with a trailing / on the URL.
Package indexes that wish to support setuptools versions prior to 0.6b4 should also follow these rules:
Homepage and download links must be preceded with "<th>Home Page" or "<th>Download URL", in addition to (or instead of) the rel="" attributes on the actual links. These marker strings do not need to be visible, or uncommented, however! For example, the following is a valid homepage link that will work with any version of setuptools:
<li> <strong>Home Page:</strong> <!-- <th>Home Page --> <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a> </li>
Even though the marker string is in an HTML comment, older versions of EasyInstall will still "see" it and know that the link that follows is the project's home page URL.
The pages described by paragraph 3(b) of the preceding section must contain the string "Index of Packages</title>" somewhere in their text. This can be inside of an HTML comment, if desired, and it can be anywhere in the page. (Note: this string MUST NOT appear on normal project pages, as described in paragraphs 2 and 3(a)!)
In addition, for compatibility with PyPI versions that do not use #md5= fragment IDs, EasyInstall uses the following regular expression to match PyPI's displayed MD5 info (broken onto two lines for readability):
<a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5
&digest=([0-9a-f]{32})">md5</a>\)
Process dependency_links.txt if found in a distribution, by adding the URLs to the list for scanning.
Use relative paths in .pth files when eggs are being installed to the same directory as the .pth file. This maximizes portability of the target directory when building applications that contain eggs.
Added easy_install-N.N script(s) for convenience when using multiple Python versions.
Added automatic handling of installation conflicts. Eggs are now shifted to the front of sys.path, in an order consistent with where they came from, making EasyInstall seamlessly co-operate with system package managers.
The --delete-conflicting and --ignore-conflicts-at-my-risk options are now no longer necessary, and will generate warnings at the end of a run if you use them.
Don't recursively traverse subdirectories given to --find-links.
