The PEAK Developers' Center   Diff for "EasyInstall" UserPreferences
 
HelpContents Search Diffs Info Edit Subscribe XML Print View
Ignore changes in the amount of whitespace

Differences between version dated 2006-06-09 14:35:35 and 2009-10-20 10:08:25 (spanning 20 versions)

Deletions are marked like this.
Additions are marked like this.

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 <http://peak.telecommunity.com/DevCenter/PackageNotes>`_
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
<http://peak.telecommunity.com/DevCenter/UserPreferences>`_ page. Thanks!)
Please share your experiences with us! If you encounter difficulty installing
a package, please contact us via the `distutils mailing list
<http://mail.python.org/pipermail/distutils-sig/>`_. (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

Installing "Easy Install"
-------------------------
 
Download `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_, and
run it; this will download and install the appropriate ``setuptools`` egg for
your Python version. (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. (Windows users, don't
put ``ez_setup.py`` inside your Python installation; please put it in some
other directory before running it.)
 
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``.
 
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. In particular, you can use the --script-dir option to
direct script installation to a custom location. You should not, however,
use custom installation locations without first reading the section below on
`Custom Installation Locations`_.
 
The instructions you've just read assume that:
 
* You are installling to Python's primary ``site-packages`` directory
 
* You have unrestricted internet access on the computer where you are
  installing.
 
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 <http://ntlmaps.sf.net/>`_, which lets you get past such firewalls
in the same way that your web browser(s) do. This will let ``ez_setup.py``
download the setuptools egg.
 
If you can't use APS, or don't have internet access at all, you will need to
first download the appropriate ``.egg`` file from the `setuptools PyPI page
<http://cheeseshop.python.org/pypi/setuptools>`_ using a computer with internet
access. Place the egg in the same directory as ``ez_setup.py`` on the target
computer before running it.
 
If you are installing to a custom location or do not have write access to
Python's primary ``site-packages`` directory, please also see the section below
on `Custom Installation Locations`_ for more detailed instructions.
Please see the `setuptools PyPI page <http://pypi.python.org/pypi/setuptools>`_
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 <http://ntlmaps.sf.net/>`_, 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.)
 
 
Troubleshooting

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

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.
 
 
Restricting Downloads with ``--allow-hosts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.
 
 
Packaging Others' Projects As Eggs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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"`_.
 
 
Password-Protected Sites
~~~~~~~~~~~~~~~~~~~~~~~~
 
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.
 
 
Controlling Build Options
~~~~~~~~~~~~~~~~~~~~~~~~~

    installed package to work, like manually adding it to ``PYTHONPATH`` or to
    ``sys.path`` at runtime.
 
``--index-url=URL, -i URL`` (New in 0.4a1)
``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
    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
    http://pypi.python.org/simple 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

    script directories, and does not override the ones set on the command line
    or in a configuration file.
 
``--local-snapshots-ok, -l`` (New in 0.6c6)
    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.
 
 
.. _non-root installation:
 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
If you are on a Mac OS X machine, you should just use the
``~/Library/Python2.x/site-packages`` directory as your custom installation
``~/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.
 

file with the following contents (or add this to the existing contents)::
 
    [install]
    install_lib = ~/Library/Python$py_version_short/site-packages
    install_lib = ~/Library/Python/$py_version_short/site-packages
    install_scripts = ~/bin
 
This will tell the distutils and EasyInstall to always install packages in

set, if you haven't already got this set up on your machine.
 
 
Package Index "API"
-------------------
 
Custom package indexes (and PyPI) must follow the following rules for
EasyInstall to be able to look up and download packages:
 
1. Except where stated otherwise, "pages" are HTML or XHTML, and "links"
   refer to ``href`` attributes.
 
2. Individual project version pages' URLs must be of the form
   ``base/projectname/version``, where ``base`` is the package index's base URL.
 
3. Omitting the ``/version`` part of a project page's URL (but keeping the
   trailing ``/``) should result in a page that is either:
 
   a) The single active version of that project, as though the version had been
      explicitly included, OR
 
   b) A page with links to all of the active version pages for that project.
 
4. 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.
 
5. 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.
 
6. 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.
 
7. 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.)
 
8. 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.
 
 
Backward Compatibility
~~~~~~~~~~~~~~~~~~~~~~
 
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
    &amp;digest=([0-9a-f]{32})">md5</a>\)
 
 
Release Notes/Change History
============================
 
0.6c11
 * Fix installed script .exe files not working with 64-bit Python on Windows
   (wasn't actually released in 0.6c10 due to a lost checkin)
 
0.6c10
 * Fix easy_install.exe giving UAC errors on Windows Vista
 
 * Support for the most recent Sourceforge download link insanity
 
 * Stop crashing on certain types of HTTP error
 
 * Stop re-trying URLs that already failed retrieval once
 
 * Fixes for various dependency management problems such as looping builds,
   re-downloading packages already present on sys.path (but not in a registered
   "site" directory), and semi-randomly preferring local "-f" packages over
   local installed packages
 
0.6c9
 * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting
   is flattened out in the resulting egg. (There was a case-sensitivity
   problem that affected some distributions, notably ``pywin32``.)
 
 * Prevent ``--help-commands`` and other junk from showing under Python 2.5
   when running ``easy_install --help``.
 
 * Fixed GUI scripts sometimes not executing on Windows
 
 * Fixed not picking up dependency links from recursive dependencies.
 
 * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs
 
 * Changes for Jython compatibility
 
 * Improved error message when a requirement is also a directory name, but the
   specified directory is not a source package.
 
 * Fixed ``--allow-hosts`` option blocking ``file:`` URLs
 
 * Fixed HTTP SVN detection failing when the page title included a project
   name (e.g. on SourceForge-hosted SVN)
 
 * Fix Jython script installation to handle ``#!`` lines better when
   ``sys.executable`` is a script.
 
 * Removed use of deprecated ``md5`` module if ``hashlib`` is available
 
 * Keep site directories (e.g. ``site-packages``) from being included in
   ``.pth`` files.
 
0.6c7
 * ``ftp:`` download URLs now work correctly.
 
 * The default ``--index-url`` is now ``http://pypi.python.org/simple``, to use
   the Python Package Index's new simpler (and faster!) REST API.
 
0.6c6
 * EasyInstall no longer aborts the installation process if a URL it wants to
   retrieve can't be downloaded, unless the URL is an actual package download.
   Instead, it issues a warning and tries to keep going.
 
 * Fixed distutils-style scripts originally built on Windows having their line
   endings doubled when installed on any platform.
 
 * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects
   installed using ``setup.py develop``.
 
 * Fixed not HTML-decoding URLs scraped from web pages
  
0.6c5
 * Fixed ``.dll`` files on Cygwin not having executable permisions when an egg
   is installed unzipped.
 
0.6c4
 * Added support for HTTP "Basic" authentication using ``http://user:pass@host``
   URLs. If a password-protected page contains links to the same host (and
   protocol), those links will inherit the credentials used to access the
   original page.
 
 * Removed all special support for Sourceforge mirrors, as Sourceforge's
   mirror system now works well for non-browser downloads.
 
 * Fixed not recognizing ``win32.exe`` installers that included a custom
   bitmap.
 
 * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they
   are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as
   is done by ``os.urandom()`` on some platforms).
 
 * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable``
   has a space in it (e.g., the user installed Python to a ``Program Files``
   directory).
 
0.6c3
 * You can once again use "python -m easy_install" with Python 2.4 and above.
 
 * Python 2.5 compatibility fixes added.
 
0.6c2
 * Windows script wrappers now support quoted arguments and arguments
   containing spaces. (Patch contributed by Jim Fulton.)
 
 * The ``ez_setup.py`` script now actually works when you put a setuptools
   ``.egg`` alongside it for bootstrapping an offline machine.
 
 * A writable installation directory on ``sys.path`` is no longer required to
   download and extract a source distribution using ``--editable``.
 
 * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable``
   contains non-ASCII characters, to prevent deprecation warnings about an
   unspecified encoding when the script is run.
 
0.6c1
 * EasyInstall now includes setuptools version information in the
   ``User-Agent`` string sent to websites it visits.
 
0.6b4
 * Fix creating Python wrappers for non-Python scripts
 
 * Fix ``ftp://`` directory listing URLs from causing a crash when used in the
   "Home page" or "Download URL" slots on PyPI.
 
 * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile
   or directory is deleted/overwritten.
 
 * Fix not recognizing HTML 404 pages from package indexes.
 
 * Allow ``file://`` URLs to be used as a package index. URLs that refer to
   directories will use an internally-generated directory listing if there is
   no ``index.html`` file in the directory.
 
 * Allow external links in a package index to be specified using
   ``rel="homepage"`` or ``rel="download"``, without needing the old
   PyPI-specific visible markup.
 
 * Suppressed warning message about possibly-misspelled project name, if an egg
   or link for that project name has already been seen.
 
0.6b3
 * Fix local ``--find-links`` eggs not being copied except with
   ``--always-copy``.

* 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?
 

PythonPowered
ShowText of this page
EditText of this page
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck