============ Easy Install ============ 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! 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!) (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.) .. contents:: **Table of Contents** Using "Easy Install" ==================== Installing "Easy Install" ------------------------- 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. If you do not have write access to your computer's ``site-packages`` directory, please also see the section below on `Non-Root Installation`_ for more detailed instructions on pre-configuring your system for the best usability with EasyInstall, then return here for the remaining steps. Download `ez_setup.py `_, and run it; this will download and install the appropriate ``setuptools`` egg for your Python version. You may receive a message telling you about an obsolete version of setuptools being present; if so, you must be sure to delete it entirely, along with the old ``pkg_resources`` module if it's present on ``sys.path``. An ``easy_install.py`` script will be installed in the normal location for Python scripts on your platform. In the examples below, you'll need to replace references to ``easy_install`` with the correct invocation to run ``easy_install.py`` on your system. If you have Python 2.4 or better, you can also use ``python -m easy_install``, which will have the same effect, but which may be easier for you to type. (Note: the ``ez_setup.py`` script accepts the same `Command-Line Options`_ and `Configuration Files`_ as ``easy_install`` itself, so you can use them to control its behavior. However, you should avoid using a custom installation directory or doing multi-version installs of the setuptools package, because this may make it impossible for scripts installed with EasyInstall to access it afterwards.) Downloading and Installing a Package ------------------------------------ For basic use of ``easy_install``, you need only supply the filename or URL of a source distribution or .egg file (`Python Egg`__). __ http://peak.telecommunity.com/DevCenter/PythonEggs **Example 1**. Install a package by name, searching PyPI for the latest version, and automatically downloading, building, and installing it:: easy_install SQLObject **Example 2**. Install or upgrade a package by name and version by finding links on a given "download page":: easy_install -f http://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. 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" 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`` (or installing outside of ``site-packages``), 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 Python's ``site-packages`` 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 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 ``rst2html.py`` to ``r2h_039``, and install another version:: easy_install -m docutils==0.3.10 This will create another ``rst2html.py`` script, this one using docutils version 0.3.10 instead of 0.3.9. You now have two scripts, each using a different version of the package. (Notice that we used ``-m`` for both installations, so that Python won't lock us out of using anything but the most recently-installed version of the package.) Controlling Build Options ------------------------- EasyInstall respects standard distutils `Configuration Files`_, so you can use them to configure build options for packages that it installs from source. For example, if you are on Windows using the MinGW compiler, you can configure the default compiler by putting something like this:: [build] compiler = mingw32 into the appropriate distutils configuration file. In fact, since this is just normal distutils configuration, it will affect any builds using that config file, not just ones done by EasyInstall. For example, if you add those lines to ``distutils.cfg`` in the ``distutils`` package directory, it will be the default compiler for *all* packages you build. See `Configuration Files`_ below for a list of the standard configuration file locations, and links to more documentation on using distutils configuration files. Editing and Viewing Source Packages ----------------------------------- 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 Dealing with Installation Conflicts ----------------------------------- 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! Compressed Installation ----------------------- EasyInstall tries to install packages in zipped form, if it can. Zipping packages can significantly increase Python's overall import performance if you're installing to``site-packages`` and not using the ``--multi`` 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 very 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()``) * Any data files or C extensions (this restriction will be removed in a future release, once the ``pkg_resources`` runtime has been hardened for multi-user environments) 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.) Reference Manual ================ Configuration Files ------------------- (New in 0.4a2) You may specify default options for EasyInstall using the standard distutils configuration files, under the command heading ``easy_install``. EasyInstall will look first for a ``setup.cfg`` file in the current directory, then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes and Windows, respectively), and finally a ``distutils.cfg`` file in the ``distutils`` package directory. Here's a simple example:: [easy_install] # set the default location to install packages install_dir = /home/me/lib/python # Notice that indentation can be used to continue an option # value; this is especially useful for the "--find-links" # option, which tells easy_install to use download links on # these pages before consulting PyPI: # find_links = http://sqlobject.org/ http://peak.telecommunity.com/dist/ In addition to accepting configuration for its own options under ``[easy_install]``, EasyInstall also respects defaults specified for other distutils commands. For example, if you don't set an ``install_dir`` for ``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]`` command, this will become EasyInstall's default installation directory. Thus, if you are already using distutils configuration files to set default install locations, build options, etc., EasyInstall will respect your existing settings until and unless you override them explicitly in an ``[easy_install]`` section. For more information, see also the current Python documentation on the `use and location of distutils configuration files `_. Command-Line Options -------------------- ``--zip-ok, -z`` Install all packages as zip files, even if they are marked as unsafe for running as a zipfile. This can be useful when EasyInstall's analysis of a non-setuptools package is too conservative, but keep in mind that the package may not work correctly. (Changed in 0.5a9; previously this option was required in order for zipped installation to happen at all.) ``--always-unzip, -Z`` 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, -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. ``--upgrade, -U`` (New in 0.5a4) By default, EasyInstall only searches the Python Package Index if a project/version requirement can't be met by distributions already installed on sys.path or the installation directory. However, if you supply the ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package index before selecting a version to install. In this way, you can force EasyInstall to use the latest available version of any package it installs (subject to any version requirements that might exclude such later versions). ``--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. ``--always-copy, -a`` (New in 0.5a4) 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. ``--find-links=URL, -f URL`` (Option renamed in 0.4a2) Scan the specified "download pages" for direct links to downloadable eggs or source distributions. Any usable packages will be downloaded if they are required by a command line argument. For example, this:: easy_install -f http://peak.telecommunity.com/dist PyProtocols will download and install the latest version of PyProtocols linked from the PEAK downloads page, but ignore the other download links on that page. If all requested packages can be found using links on the specified download pages, the Python Package Index will *not* be consulted. You can use a ``file:`` URL to reference a local HTML file containing links, or you can just use the name of a directory containing "distribution files" (source archives, eggs, Windows installers, etc.), and EasyInstall will then be aware of the files available there. You may specify multiple URLs or directories 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; 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. ``--delete-conflicting, -D`` (New in 0.5a9) 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. ``--ignore-conflicts-at-my-risk`` (New in 0.5a9) 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. ``--index-url=URL, -u URL`` (New in 0.4a1) Specifies the base URL of the Python Package Index. The default is http://www.python.org/pypi if not specified. When a package is requested that is not locally available or linked from a ``--find-links`` download page, the package index will be searched for download pages for the needed package, and those download pages will be searched for links to download an egg or source distribution. ``--editable, -e`` (New in 0.6a1) Only find and download source distributions for the specified projects, unpacking them to subdirectories of the specified ``--build-directory``. EasyInstall will not actually build or install the requested projects or their dependencies; it will just find and extract them for you. See `Editing and Viewing Source Packages`_ above for more details. ``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1) 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. ``--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). ``--record=FILENAME`` (New in 0.5a4) Write a record of all installed files to FILENAME. This is basically the same as the same option for the standard distutils "install" command, and is included for compatibility with tools that expect to pass this option to "setup.py install". ``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1) 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. By default, EasyInstall only knows about Python-defined "site" directories, not those that may be added by an OS distribution or site administrator calling ``site.addsitedir()``. You should not normally need to use this option directly, as your system administrator should configure it in the ``distutils.cfg`` file of the Python installation. For example, if the administrator wants to make each user's ``~/lib/python2.3`` directory be a "site" directory, he or she should create an ``altinstall.pth`` file in the normal site-packages directory, containing this:: import os, site; site.addsitedir(os.path.expanduser('~/lib/python2.3')) and a ``distutils.cfg`` file inside the ``distutils`` package directory, containing this:: [easy_install] site_dirs = ~/lib/python23 This will ensure that EasyInstall knows about the additional "site" directory, thereby allowing individual users to install their own Python packages via EasyInstall. Non-Root Installation --------------------- If you want to use EasyInstall on a computer where you do not have write access to Python's main ``site-packages`` directory, you may need to set up an alternate "home" location for Python, so that it uses a personal ``site-packages`` directory instead of the system-wide ``site-packages``. If you are on a Mac OS X machine, you should just use the ``~/Library/Python2.x/site-packages`` directory (replacing the ``x`` with the appropriate number). Just make sure the directory exists, and use it as your installation location for all packages (including EasyInstall itself). To make the distutils install to this personal ``site-packages`` directory by default, you should create a ``~/.pydistutils.cfg`` file with the following contents:: [install] install_lib = ~/Library/Python$py_version_short/site-packages This will tell the distutils (and EasyInstall) to always install packages in the appropriate personal ``site-packages`` directory. (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 will work correctly no matter what Python version you use, now or in the future.) If you are on a Linux, BSD, Cygwin, or other similar Unix-like operating system, you should create a ``~/lib/python2.x/site-packages`` directory instead. You will need to know your Python version's ``sys.prefix`` and ``sys.exec_prefix``, which you can find out by running:: python -c "import sys; print sys.prefix; print sys.exec_prefix" (Replace "python" with the right path or version for your platform.) Assuming your ``sys.prefix`` is ``/usr/local``, and you are working with Python 2.4, you need to then perform the following steps (possibly making adjustments for the tools available on your platform). First, you need to set up the local library directories, by symlinking to the system Python's libraries:: mkdir -p ~/lib/python2.4 ln -s /usr/local/lib/python2.4/* ~/lib/python2.4/ rm ~/lib/python2.4/site-packages mkdir ~/lib/python2.4/site-packages ln -s /usr/local/lib/python2.4/site-packages/* ~/lib/python2.4/site-packages If your ``sys.exec_prefix`` was different from your ``sys.prefix``, you will also need to do this:: ln -s /execprefix/lib/python2.4/* ~/lib/python2.4/ replacing ``execprefix`` in the above with the value of ``sys.exec_prefix``. Finally, you will also need a private ``python`` executable, e.g.:: mkdir -p ~/bin ln /usr/local/bin/python2.4 ~/bin/python Note that if hardlinking as shown doesn't work (e.g. because the system Python is on a different filesystem), you should use ``copy -p`` instead of ``ln``. Do NOT use a symlink! The Python binary must be copied or hardlinked, otherwise it will use the system ``site-packages`` directory and not yours. 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 and relocate any older installed modules to your new ``~/lib/python2.x/site-packages`` directory. Also note that you must now make sure to use the ``~/bin/python`` executable instead of the system Python, and ideally you should put the ``~/bin`` directory first on your ``PATH`` as well, because that is where EasyInstall will install new Python scripts. 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. * Wrapping ``easy_install.py`` with the Exemaker utility may cause failures when building packages that want to compile themselves with optimization enabled. This is because Exemaker sets ``sys.executable`` to point to the ``easy_install`` wrapper, instead of to the Python executable, and the ``distutils.util.byte_compile()`` function expects to be able to invoke ``sys.executable`` to run a short Python script. Unfortunately, this can't be directly fixed by EasyInstall; it has to be fixed in the distutils or in Exemaker. So, don't use Exemaker to wrap ``easy_install.py``, or at any rate don't expect it to work with all packages. 0.6a1 * EasyInstall now does MD5 validation of downloads from PyPI, or from any link that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest. * EasyInstall now handles symlinks in target directories by removing the link, rather than attempting to overwrite the link's destination. This makes it easier to set up an alternate Python "home" directory (as described above in the `Non-Root Installation`_ section). * Added support for handling MacOS platform information in ``.egg`` filenames, based on a contribution by Kevin Dangoor. You may wish to delete and reinstall any eggs whose filename includes "darwin" and "Power_Macintosh", because the format for this platform information has changed so that minor OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a previous OS version to become obsolete. * easy_install's dependency processing algorithms have changed. When using ``--always-copy``, it now ensures that dependencies are copied too. When not using ``--always-copy``, it tries to use a single resolution loop, rather than recursing. * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py`` extensions. * Added ``--site-dirs`` option to allow adding custom "site" directories. Made ``easy-install.pth`` work in platform-specific alternate site directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X). * If you manually delete the current version of a package, the next run of EasyInstall against the target directory will now remove the stray entry from the ``easy-install.pth`` file. * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID as pointing to the named project's source checkout. Such URLs have a lower match precedence than any other kind of distribution, so they'll only be used if they have a higher version number than any other available distribution, or if you use the ``--editable`` option. The ``#egg`` fragment can contain a version if it's formatted as ``#egg=proj-ver``, where ``proj`` is the project name, and ``ver`` is the version number. You *must* use the format for these values that the ``bdist_egg`` command uses; i.e., all non-alphanumeric runs must be condensed to single underscore characters. * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_ above for more info. Also, slightly changed the behavior of the ``--build-directory`` option. * Fixed the setup script sandbox facility not recognizing certain paths as valid on case-insensitive platforms. 0.5a12 * Fix ``python -m easy_install`` not working due to setuptools being installed as a zipfile. Update safety scanner to check for modules that might be used as ``python -m`` scripts. * Misc. fixes for win32.exe support, including changes to support Python 2.4's changed ``bdist_wininst`` format. 0.5a10 * Put the ``easy_install`` module back in as a module, as it's needed for ``python -m`` to run it! * Allow ``--find-links/-f`` to accept local directories or filenames as well as URLs. 0.5a9 * EasyInstall now automatically detects when an "unmanaged" package or module is going to be on ``sys.path`` ahead of a package you're installing, thereby preventing the newer version from being imported. By default, it will abort installation to alert you of the problem, but there are also new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``) available to change the default behavior. (Note: this new feature doesn't take effect for egg files that were built with older ``setuptools`` versions, because they lack the new metadata file required to implement it.) * The ``easy_install`` distutils command now uses ``DistutilsError`` as its base error type for errors that should just issue a message to stderr and exit the program without a traceback. * EasyInstall can now be given a path to a directory containing a setup script, and it will attempt to build and install the package there. * EasyInstall now performs a safety analysis on module contents to determine whether a package is likely to run in zipped form, and displays information about what modules may be doing introspection that would break when running as a zipfile. * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that would ordinarily be considered safe to unzip, and changed the meaning of ``--zip-ok/-z`` to "always leave everything zipped". 0.5a8 * There is now a separate documentation page for `setuptools`_; revision history that's not specific to EasyInstall has been moved to that page. .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools 0.5a5 * Made ``easy_install`` a standard ``setuptools`` command, moving it from the ``easy_install`` module to ``setuptools.command.easy_install``. Note that if you were importing or extending it, you must now change your imports accordingly. ``easy_install.py`` is still installed as a script, but not as a module. 0.5a4 * Added ``--always-copy/-a`` option to always copy needed packages to the installation directory, even if they're already present elsewhere on sys.path. (In previous versions, this was the default behavior, but now you must request it.) * Added ``--upgrade/-U`` option to force checking PyPI for latest available version(s) of all packages requested by name and version, even if a matching version is available locally. * Added automatic installation of dependencies declared by a distribution being installed. These dependencies must be listed in the distribution's ``EGG-INFO`` directory, so the distribution has to have declared its dependencies by using setuptools. If a package has requirements it didn't declare, you'll still have to deal with them yourself. (E.g., by asking EasyInstall to find and install them.) * Added the ``--record`` option to ``easy_install`` for the benefit of tools that run ``setup.py install --record=filename`` on behalf of another packaging system.) 0.5a3 * Fixed not setting script permissions to allow execution. * Improved sandboxing so that setup scripts that want a temporary directory (e.g. pychecker) can still run in the sandbox. 0.5a2 * Fix stupid stupid refactoring-at-the-last-minute typos. :( 0.5a1 * Added support for converting ``.win32.exe`` installers to eggs on the fly. EasyInstall will now recognize such files by name and install them. * Fixed a problem with picking the "best" version to install (versions were being sorted as strings, rather than as parsed values) 0.4a4 * Added support for the distutils "verbose/quiet" and "dry-run" options, as well as the "optimize" flag. * Support downloading packages that were uploaded to PyPI (by scanning all links on package pages, not just the homepage/download links). 0.4a3 * Add progress messages to the search/download process so that you can tell what URLs it's reading to find download links. (Hopefully, this will help people report out-of-date and broken links to package authors, and to tell when they've asked for a package that doesn't exist.) 0.4a2 * Added support for installing scripts * Added support for setting options via distutils configuration files, and using distutils' default options as a basis for EasyInstall's defaults. * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the script installation directory option. * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if Python includes SSL support. 0.4a1 * Added ``--scan-url`` and ``--index-url`` options, to scan download pages and search PyPI for needed packages. 0.3a4 * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single URL installs, to avoid running the wrong setup.py. 0.3a3 * Added ``--build-directory=DIR/-b DIR`` option. * Added "installation report" that explains how to use 'require()' when doing a multiversion install or alternate installation directory. * Added SourceForge mirror auto-select (Contributed by Ian Bicking) * Added "sandboxing" that stops a setup script from running if it attempts to write to the filesystem outside of the build area * Added more workarounds for packages with quirky ``install_data`` hacks 0.3a2 * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking) * Misc. bug fixes 0.3a1 * Initial release. Future Plans ============ * Additional utilities to list/remove/verify packages * Signature checking? SSL? Ability to suppress PyPI search? * Display byte progress meter when downloading distributions and long pages? * Redirect stdout/stderr to log during run_setup?