1============ 2Easy Install 3============ 4 5Easy Install is a python module (``easy_install``) bundled with ``setuptools`` 6that lets you automatically download, build, install, and manage Python 7packages. 8 9Please share your experiences with us! If you encounter difficulty installing 10a package, please contact us via the `distutils mailing list 11<http://mail.python.org/pipermail/distutils-sig/>`_. (Note: please DO NOT send 12private email directly to the author of setuptools; it will be discarded. The 13mailing list is a searchable archive of previously-asked and answered 14questions; you should begin your research there before reporting something as a 15bug -- and then do so via list discussion first.) 16 17(Also, if you'd like to learn about how you can use ``setuptools`` to make your 18own packages work better with EasyInstall, or provide EasyInstall-like features 19without requiring your users to use EasyInstall directly, you'll probably want 20to check out the full `setuptools`_ documentation as well.) 21 22.. contents:: **Table of Contents** 23 24 25Using "Easy Install" 26==================== 27 28 29.. _installation instructions: 30 31Installing "Easy Install" 32------------------------- 33 34Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_ 35for download links and basic installation instructions for each of the 36supported platforms. 37 38You will need at least Python 3.3 or 2.7. An ``easy_install`` script will be 39installed in the normal location for Python scripts on your platform. 40 41Note that the instructions on the setuptools PyPI page assume that you are 42are installing to Python's primary ``site-packages`` directory. If this is 43not the case, you should consult the section below on `Custom Installation 44Locations`_ before installing. (And, on Windows, you should not use the 45``.exe`` installer when installing to an alternate location.) 46 47Note that ``easy_install`` normally works by downloading files from the 48internet. If you are behind an NTLM-based firewall that prevents Python 49programs from accessing the net directly, you may wish to first install and use 50the `APS proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such 51firewalls in the same way that your web browser(s) do. 52 53(Alternately, if you do not wish easy_install to actually download anything, you 54can restrict it from doing so with the ``--allow-hosts`` option; see the 55sections on `restricting downloads with --allow-hosts`_ and `command-line 56options`_ for more details.) 57 58 59Troubleshooting 60~~~~~~~~~~~~~~~ 61 62If EasyInstall/setuptools appears to install correctly, and you can run the 63``easy_install`` command but it fails with an ``ImportError``, the most likely 64cause is that you installed to a location other than ``site-packages``, 65without taking any of the steps described in the `Custom Installation 66Locations`_ section below. Please see that section and follow the steps to 67make sure that your custom location will work correctly. Then re-install. 68 69Similarly, if you can run ``easy_install``, and it appears to be installing 70packages, but then you can't import them, the most likely issue is that you 71installed EasyInstall correctly but are using it to install packages to a 72non-standard location that hasn't been properly prepared. Again, see the 73section on `Custom Installation Locations`_ for more details. 74 75 76Windows Notes 77~~~~~~~~~~~~~ 78 79Installing setuptools will provide an ``easy_install`` command according to 80the techniques described in `Executables and Launchers`_. If the 81``easy_install`` command is not available after installation, that section 82provides details on how to configure Windows to make the commands available. 83 84 85Downloading and Installing a Package 86------------------------------------ 87 88For basic use of ``easy_install``, you need only supply the filename or URL of 89a source distribution or .egg file (`Python Egg`__). 90 91__ http://peak.telecommunity.com/DevCenter/PythonEggs 92 93**Example 1**. Install a package by name, searching PyPI for the latest 94version, and automatically downloading, building, and installing it:: 95 96 easy_install SQLObject 97 98**Example 2**. Install or upgrade a package by name and version by finding 99links on a given "download page":: 100 101 easy_install -f http://pythonpaste.org/package_index.html SQLObject 102 103**Example 3**. Download a source distribution from a specified URL, 104automatically building and installing it:: 105 106 easy_install http://example.com/path/to/MyPackage-1.2.3.tgz 107 108**Example 4**. Install an already-downloaded .egg file:: 109 110 easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg 111 112**Example 5**. Upgrade an already-installed package to the latest version 113listed on PyPI:: 114 115 easy_install --upgrade PyProtocols 116 117**Example 6**. Install a source distribution that's already downloaded and 118extracted in the current directory (New in 0.5a9):: 119 120 easy_install . 121 122**Example 7**. (New in 0.6a1) Find a source distribution or Subversion 123checkout URL for a package, and extract it or check it out to 124``~/projects/sqlobject`` (the name will always be in all-lowercase), where it 125can be examined or edited. (The package will not be installed, but it can 126easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing 127and Viewing Source Packages`_ below for more info.):: 128 129 easy_install --editable --build-directory ~/projects SQLObject 130 131**Example 7**. (New in 0.6.11) Install a distribution within your home dir:: 132 133 easy_install --user SQLAlchemy 134 135Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils`` 136"distribution" names), and package+version specifiers. In each case, it will 137attempt to locate the latest available version that meets your criteria. 138 139When downloading or processing downloaded files, Easy Install recognizes 140distutils source distribution files with extensions of .tgz, .tar, .tar.gz, 141.tar.bz2, or .zip. And of course it handles already-built .egg 142distributions as well as ``.win32.exe`` installers built using distutils. 143 144By default, packages are installed to the running Python installation's 145``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir`` 146option to specify an alternative directory, or specify an alternate location 147using distutils configuration files. (See `Configuration Files`_, below.) 148 149By default, any scripts included with the package are installed to the running 150Python installation's standard script installation location. However, if you 151specify an installation directory via the command line or a config file, then 152the default directory for installing scripts will be the same as the package 153installation directory, to ensure that the script will have access to the 154installed package. You can override this using the ``-s`` or ``--script-dir`` 155option. 156 157Installed packages are added to an ``easy-install.pth`` file in the install 158directory, so that Python will always use the most-recently-installed version 159of the package. If you would like to be able to select which version to use at 160runtime, you should use the ``-m`` or ``--multi-version`` option. 161 162 163Upgrading a Package 164------------------- 165 166You don't need to do anything special to upgrade a package: just install the 167new version, either by requesting a specific version, e.g.:: 168 169 easy_install "SomePackage==2.0" 170 171a version greater than the one you have now:: 172 173 easy_install "SomePackage>2.0" 174 175using the upgrade flag, to find the latest available version on PyPI:: 176 177 easy_install --upgrade SomePackage 178 179or by using a download page, direct download URL, or package filename:: 180 181 easy_install -f http://example.com/downloads ExamplePackage 182 183 easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg 184 185 easy_install my_downloads/ExamplePackage-2.0.tgz 186 187If you're using ``-m`` or ``--multi-version`` , using the ``require()`` 188function at runtime automatically selects the newest installed version of a 189package that meets your version criteria. So, installing a newer version is 190the only step needed to upgrade such packages. 191 192If you're installing to a directory on PYTHONPATH, or a configured "site" 193directory (and not using ``-m``), installing a package automatically replaces 194any previous version in the ``easy-install.pth`` file, so that Python will 195import the most-recently installed version by default. So, again, installing 196the newer version is the only upgrade step needed. 197 198If you haven't suppressed script installation (using ``--exclude-scripts`` or 199``-x``), then the upgraded version's scripts will be installed, and they will 200be automatically patched to ``require()`` the corresponding version of the 201package, so that you can use them even if they are installed in multi-version 202mode. 203 204``easy_install`` never actually deletes packages (unless you're installing a 205package with the same name and version number as an existing package), so if 206you want to get rid of older versions of a package, please see `Uninstalling 207Packages`_, below. 208 209 210Changing the Active Version 211--------------------------- 212 213If you've upgraded a package, but need to revert to a previously-installed 214version, you can do so like this:: 215 216 easy_install PackageName==1.2.3 217 218Where ``1.2.3`` is replaced by the exact version number you wish to switch to. 219If a package matching the requested name and version is not already installed 220in a directory on ``sys.path``, it will be located via PyPI and installed. 221 222If you'd like to switch to the latest installed version of ``PackageName``, you 223can do so like this:: 224 225 easy_install PackageName 226 227This will activate the latest installed version. (Note: if you have set any 228``find_links`` via distutils configuration files, those download pages will be 229checked for the latest available version of the package, and it will be 230downloaded and installed if it is newer than your current version.) 231 232Note that changing the active version of a package will install the newly 233active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is 234specified. 235 236 237Uninstalling Packages 238--------------------- 239 240If you have replaced a package with another version, then you can just delete 241the package(s) you don't need by deleting the PackageName-versioninfo.egg file 242or directory (found in the installation directory). 243 244If you want to delete the currently installed version of a package (or all 245versions of a package), you should first run:: 246 247 easy_install -m PackageName 248 249This will ensure that Python doesn't continue to search for a package you're 250planning to remove. After you've done this, you can safely delete the .egg 251files or directories, along with any scripts you wish to remove. 252 253 254Managing Scripts 255---------------- 256 257Whenever you install, upgrade, or change versions of a package, EasyInstall 258automatically installs the scripts for the selected package version, unless 259you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in 260the script directory have the same name, they are overwritten. 261 262Thus, you do not normally need to manually delete scripts for older versions of 263a package, unless the newer version of the package does not include a script 264of the same name. However, if you are completely uninstalling a package, you 265may wish to manually delete its scripts. 266 267EasyInstall's default behavior means that you can normally only run scripts 268from one version of a package at a time. If you want to keep multiple versions 269of a script available, however, you can simply use the ``--multi-version`` or 270``-m`` option, and rename the scripts that EasyInstall creates. This works 271because EasyInstall installs scripts as short code stubs that ``require()`` the 272matching version of the package the script came from, so renaming the script 273has no effect on what it executes. 274 275For example, suppose you want to use two versions of the ``rst2html`` tool 276provided by the `docutils <http://docutils.sf.net/>`_ package. You might 277first install one version:: 278 279 easy_install -m docutils==0.3.9 280 281then rename the ``rst2html.py`` to ``r2h_039``, and install another version:: 282 283 easy_install -m docutils==0.3.10 284 285This will create another ``rst2html.py`` script, this one using docutils 286version 0.3.10 instead of 0.3.9. You now have two scripts, each using a 287different version of the package. (Notice that we used ``-m`` for both 288installations, so that Python won't lock us out of using anything but the most 289recently-installed version of the package.) 290 291 292Executables and Launchers 293------------------------- 294 295On Unix systems, scripts are installed with as natural files with a "#!" 296header and no extension and they launch under the Python version indicated in 297the header. 298 299On Windows, there is no mechanism to "execute" files without extensions, so 300EasyInstall provides two techniques to mirror the Unix behavior. The behavior 301is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be 302"executable" (default) or "natural". 303 304Regardless of the technique used, the script(s) will be installed to a Scripts 305directory (by default in the Python installation directory). It is recommended 306for EasyInstall that you ensure this directory is in the PATH environment 307variable. The easiest way to ensure the Scripts directory is in the PATH is 308to run ``Tools\Scripts\win_add2path.py`` from the Python directory. 309 310Note that instead of changing your ``PATH`` to include the Python scripts 311directory, you can also retarget the installation location for scripts so they 312go on a directory that's already on the ``PATH``. For more information see 313`Command-Line Options`_ and `Configuration Files`_. During installation, 314pass command line options (such as ``--script-dir``) to 315``ez_setup.py`` to control where ``easy_install.exe`` will be installed. 316 317 318Windows Executable Launcher 319~~~~~~~~~~~~~~~~~~~~~~~~~~~ 320 321If the "executable" launcher is used, EasyInstall will create a '.exe' 322launcher of the same name beside each installed script (including 323``easy_install`` itself). These small .exe files launch the script of the 324same name using the Python version indicated in the '#!' header. 325 326This behavior is currently default. To force 327the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to "executable". 328 329Natural Script Launcher 330~~~~~~~~~~~~~~~~~~~~~~~ 331 332EasyInstall also supports deferring to an external launcher such as 333`pylauncher <https://bitbucket.org/pypa/pylauncher>`_ for launching scripts. 334Enable this experimental functionality by setting the 335``SETUPTOOLS_LAUNCHER`` environment variable to "natural". EasyInstall will 336then install scripts as simple 337scripts with a .pya (or .pyw) extension appended. If these extensions are 338associated with the pylauncher and listed in the PATHEXT environment variable, 339these scripts can then be invoked simply and directly just like any other 340executable. This behavior may become default in a future version. 341 342EasyInstall uses the .pya extension instead of simply 343the typical '.py' extension. This distinct extension is necessary to prevent 344Python 345from treating the scripts as importable modules (where name conflicts exist). 346Current releases of pylauncher do not yet associate with .pya files by 347default, but future versions should do so. 348 349 350Tips & Techniques 351----------------- 352 353Multiple Python Versions 354~~~~~~~~~~~~~~~~~~~~~~~~ 355 356EasyInstall installs itself under two names: 357``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version 358used to install it. Thus, if you install EasyInstall for both Python 3.2 and 3592.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to 360install packages for the respective Python version. 361 362Setuptools also supplies easy_install as a runnable module which may be 363invoked using ``python -m easy_install`` for any Python with Setuptools 364installed. 365 366Restricting Downloads with ``--allow-hosts`` 367~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 368 369You can use the ``--allow-hosts`` (``-H``) option to restrict what domains 370EasyInstall will look for links and downloads on. ``--allow-hosts=None`` 371prevents downloading altogether. You can also use wildcards, for example 372to restrict downloading to hosts in your own intranet. See the section below 373on `Command-Line Options`_ for more details on the ``--allow-hosts`` option. 374 375By default, there are no host restrictions in effect, but you can change this 376default by editing the appropriate `configuration files`_ and adding: 377 378.. code-block:: ini 379 380 [easy_install] 381 allow_hosts = *.myintranet.example.com,*.python.org 382 383The above example would then allow downloads only from hosts in the 384``python.org`` and ``myintranet.example.com`` domains, unless overridden on the 385command line. 386 387 388Installing on Un-networked Machines 389~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 390 391Just copy the eggs or source packages you need to a directory on the target 392machine, then use the ``-f`` or ``--find-links`` option to specify that 393directory's location. For example:: 394 395 easy_install -H None -f somedir SomePackage 396 397will attempt to install SomePackage using only eggs and source packages found 398in ``somedir`` and disallowing all remote access. You should of course make 399sure you have all of SomePackage's dependencies available in somedir. 400 401If you have another machine of the same operating system and library versions 402(or if the packages aren't platform-specific), you can create the directory of 403eggs using a command like this:: 404 405 easy_install -zmaxd somedir SomePackage 406 407This will tell EasyInstall to put zipped eggs or source packages for 408SomePackage and all its dependencies into ``somedir``, without creating any 409scripts or .pth files. You can then copy the contents of ``somedir`` to the 410target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which 411prevents .pth files from being used, ``-a`` means to copy all the eggs needed, 412even if they're installed elsewhere on the machine, and ``-d`` indicates the 413directory to place the eggs in.) 414 415You can also build the eggs from local development packages that were installed 416with the ``setup.py develop`` command, by including the ``-l`` option, e.g.:: 417 418 easy_install -zmaxld somedir SomePackage 419 420This will use locally-available source distributions to build the eggs. 421 422 423Packaging Others' Projects As Eggs 424~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 425 426Need to distribute a package that isn't published in egg form? You can use 427EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``, 428``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and 429``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location 430where you'd like the eggs placed. By placing them in a directory that is 431published to the web, you can then make the eggs available for download, either 432in an intranet or to the internet at large. 433 434If someone distributes a package in the form of a single ``.py`` file, you can 435wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL. 436So, something like this:: 437 438 easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo 439 440will install the package as an egg, and this:: 441 442 easy_install -zmaxd. \ 443 -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo 444 445will create a ``.egg`` file in the current directory. 446 447 448Creating your own Package Index 449~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 450 451In addition to local directories and the Python Package Index, EasyInstall can 452find download links on most any web page whose URL is given to the ``-f`` 453(``--find-links``) option. In the simplest case, you can simply have a web 454page with links to eggs or Python source packages, even an automatically 455generated directory listing (such as the Apache web server provides). 456 457If you are setting up an intranet site for package downloads, you may want to 458configure the target machines to use your download site by default, adding 459something like this to their `configuration files`_: 460 461.. code-block:: ini 462 463 [easy_install] 464 find_links = http://mypackages.example.com/somedir/ 465 http://turbogears.org/download/ 466 http://peak.telecommunity.com/dist/ 467 468As you can see, you can list multiple URLs separated by whitespace, continuing 469on multiple lines if necessary (as long as the subsequent lines are indented. 470 471If you are more ambitious, you can also create an entirely custom package index 472or PyPI mirror. See the ``--index-url`` option under `Command-Line Options`_, 473below, and also the section on `Package Index "API"`_. 474 475 476Password-Protected Sites 477------------------------ 478 479If a site you want to download from is password-protected using HTTP "Basic" 480authentication, you can specify your credentials in the URL, like so:: 481 482 http://some_userid:some_password@some.example.com/some_path/ 483 484You can do this with both index page URLs and direct download URLs. As long 485as any HTML pages read by easy_install use *relative* links to point to the 486downloads, the same user ID and password will be used to do the downloading. 487 488Using .pypirc Credentials 489------------------------- 490 491In additional to supplying credentials in the URL, ``easy_install`` will also 492honor credentials if present in the .pypirc file. Teams maintaining a private 493repository of packages may already have defined access credentials for 494uploading packages according to the distutils documentation. ``easy_install`` 495will attempt to honor those if present. Refer to the distutils documentation 496for Python 2.5 or later for details on the syntax. 497 498Controlling Build Options 499~~~~~~~~~~~~~~~~~~~~~~~~~ 500 501EasyInstall respects standard distutils `Configuration Files`_, so you can use 502them to configure build options for packages that it installs from source. For 503example, if you are on Windows using the MinGW compiler, you can configure the 504default compiler by putting something like this: 505 506.. code-block:: ini 507 508 [build] 509 compiler = mingw32 510 511into the appropriate distutils configuration file. In fact, since this is just 512normal distutils configuration, it will affect any builds using that config 513file, not just ones done by EasyInstall. For example, if you add those lines 514to ``distutils.cfg`` in the ``distutils`` package directory, it will be the 515default compiler for *all* packages you build. See `Configuration Files`_ 516below for a list of the standard configuration file locations, and links to 517more documentation on using distutils configuration files. 518 519 520Editing and Viewing Source Packages 521~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 522 523Sometimes a package's source distribution contains additional documentation, 524examples, configuration files, etc., that are not part of its actual code. If 525you want to be able to examine these files, you can use the ``--editable`` 526option to EasyInstall, and EasyInstall will look for a source distribution 527or Subversion URL for the package, then download and extract it or check it out 528as a subdirectory of the ``--build-directory`` you specify. If you then wish 529to install the package after editing or configuring it, you can do so by 530rerunning EasyInstall with that directory as the target. 531 532Note that using ``--editable`` stops EasyInstall from actually building or 533installing the package; it just finds, obtains, and possibly unpacks it for 534you. This allows you to make changes to the package if necessary, and to 535either install it in development mode using ``setup.py develop`` (if the 536package uses setuptools, that is), or by running ``easy_install projectdir`` 537(where ``projectdir`` is the subdirectory EasyInstall created for the 538downloaded package. 539 540In order to use ``--editable`` (``-e`` for short), you *must* also supply a 541``--build-directory`` (``-b`` for short). The project will be placed in a 542subdirectory of the build directory. The subdirectory will have the same 543name as the project itself, but in all-lowercase. If a file or directory of 544that name already exists, EasyInstall will print an error message and exit. 545 546Also, when using ``--editable``, you cannot use URLs or filenames as arguments. 547You *must* specify project names (and optional version requirements) so that 548EasyInstall knows what directory name(s) to create. If you need to force 549EasyInstall to use a particular URL or filename, you should specify it as a 550``--find-links`` item (``-f`` for short), and then also specify 551the project name, e.g.:: 552 553 easy_install -eb ~/projects \ 554 -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \ 555 ctypes==0.9.6 556 557 558Dealing with Installation Conflicts 559~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 560 561(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that 562people using older versions of EasyInstall can consult it. As of version 5630.6a11, installation conflicts are handled automatically without deleting the 564old or system-installed packages, and without ignoring the issue. Instead, 565eggs are automatically shifted to the front of ``sys.path`` using special 566code added to the ``easy-install.pth`` file. So, if you are using version 5670.6a11 or better of setuptools, you do not need to worry about conflicts, 568and the following issues do not apply to you.) 569 570EasyInstall installs distributions in a "managed" way, such that each 571distribution can be independently activated or deactivated on ``sys.path``. 572However, packages that were not installed by EasyInstall are "unmanaged", 573in that they usually live all in one directory and cannot be independently 574activated or deactivated. 575 576As a result, if you are using EasyInstall to upgrade an existing package, or 577to install a package with the same name as an existing package, EasyInstall 578will warn you of the conflict. (This is an improvement over ``setup.py 579install``, because the ``distutils`` just install new packages on top of old 580ones, possibly combining two unrelated packages or leaving behind modules that 581have been deleted in the newer version of the package.) 582 583EasyInstall will stop the installation if it detects a conflict 584between an existing, "unmanaged" package, and a module or package in any of 585the distributions you're installing. It will display a list of all of the 586existing files and directories that would need to be deleted for the new 587package to be able to function correctly. To proceed, you must manually 588delete these conflicting files and directories and re-run EasyInstall. 589 590Of course, once you've replaced all of your existing "unmanaged" packages with 591versions managed by EasyInstall, you won't have any more conflicts to worry 592about! 593 594 595Compressed Installation 596~~~~~~~~~~~~~~~~~~~~~~~ 597 598EasyInstall tries to install packages in zipped form, if it can. Zipping 599packages can improve Python's overall import performance if you're not using 600the ``--multi-version`` option, because Python processes zipfile entries on 601``sys.path`` much faster than it does directories. 602 603As of version 0.5a9, EasyInstall analyzes packages to determine whether they 604can be safely installed as a zipfile, and then acts on its analysis. (Previous 605versions would not install a package as a zipfile unless you used the 606``--zip-ok`` option.) 607 608The current analysis approach is fairly conservative; it currently looks for: 609 610 * Any use of the ``__file__`` or ``__path__`` variables (which should be 611 replaced with ``pkg_resources`` API calls) 612 613 * Possible use of ``inspect`` functions that expect to manipulate source files 614 (e.g. ``inspect.getsource()``) 615 616 * Top-level modules that might be scripts used with ``python -m`` (Python 2.4) 617 618If any of the above are found in the package being installed, EasyInstall will 619assume that the package cannot be safely run from a zipfile, and unzip it to 620a directory instead. You can override this analysis with the ``-zip-ok`` flag, 621which will tell EasyInstall to install the package as a zipfile anyway. Or, 622you can use the ``--always-unzip`` flag, in which case EasyInstall will always 623unzip, even if its analysis says the package is safe to run as a zipfile. 624 625Normally, however, it is simplest to let EasyInstall handle the determination 626of whether to zip or unzip, and only specify overrides when needed to work 627around a problem. If you find you need to override EasyInstall's guesses, you 628may want to contact the package author and the EasyInstall maintainers, so that 629they can make appropriate changes in future versions. 630 631(Note: If a package uses ``setuptools`` in its setup script, the package author 632has the option to declare the package safe or unsafe for zipped usage via the 633``zip_safe`` argument to ``setup()``. If the package author makes such a 634declaration, EasyInstall believes the package's author and does not perform its 635own analysis. However, your command-line option, if any, will still override 636the package author's choice.) 637 638 639Reference Manual 640================ 641 642Configuration Files 643------------------- 644 645(New in 0.4a2) 646 647You may specify default options for EasyInstall using the standard 648distutils configuration files, under the command heading ``easy_install``. 649EasyInstall will look first for a ``setup.cfg`` file in the current directory, 650then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes 651and Windows, respectively), and finally a ``distutils.cfg`` file in the 652``distutils`` package directory. Here's a simple example: 653 654.. code-block:: ini 655 656 [easy_install] 657 658 # set the default location to install packages 659 install_dir = /home/me/lib/python 660 661 # Notice that indentation can be used to continue an option 662 # value; this is especially useful for the "--find-links" 663 # option, which tells easy_install to use download links on 664 # these pages before consulting PyPI: 665 # 666 find_links = http://sqlobject.org/ 667 http://peak.telecommunity.com/dist/ 668 669In addition to accepting configuration for its own options under 670``[easy_install]``, EasyInstall also respects defaults specified for other 671distutils commands. For example, if you don't set an ``install_dir`` for 672``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]`` 673command, this will become EasyInstall's default installation directory. Thus, 674if you are already using distutils configuration files to set default install 675locations, build options, etc., EasyInstall will respect your existing settings 676until and unless you override them explicitly in an ``[easy_install]`` section. 677 678For more information, see also the current Python documentation on the `use and 679location of distutils configuration files <https://docs.python.org/install/index.html#inst-config-files>`_. 680 681Notice that ``easy_install`` will use the ``setup.cfg`` from the current 682working directory only if it was triggered from ``setup.py`` through the 683``install_requires`` option. The standalone command will not use that file. 684 685Command-Line Options 686-------------------- 687 688``--zip-ok, -z`` 689 Install all packages as zip files, even if they are marked as unsafe for 690 running as a zipfile. This can be useful when EasyInstall's analysis 691 of a non-setuptools package is too conservative, but keep in mind that 692 the package may not work correctly. (Changed in 0.5a9; previously this 693 option was required in order for zipped installation to happen at all.) 694 695``--always-unzip, -Z`` 696 Don't install any packages as zip files, even if the packages are marked 697 as safe for running as a zipfile. This can be useful if a package does 698 something unsafe, but not in a way that EasyInstall can easily detect. 699 EasyInstall's default analysis is currently very conservative, however, so 700 you should only use this option if you've had problems with a particular 701 package, and *after* reporting the problem to the package's maintainer and 702 to the EasyInstall maintainers. 703 704 (Note: the ``-z/-Z`` options only affect the installation of newly-built 705 or downloaded packages that are not already installed in the target 706 directory; if you want to convert an existing installed version from 707 zipped to unzipped or vice versa, you'll need to delete the existing 708 version first, and re-run EasyInstall.) 709 710``--multi-version, -m`` 711 "Multi-version" mode. Specifying this option prevents ``easy_install`` from 712 adding an ``easy-install.pth`` entry for the package being installed, and 713 if an entry for any version the package already exists, it will be removed 714 upon successful installation. In multi-version mode, no specific version of 715 the package is available for importing, unless you use 716 ``pkg_resources.require()`` to put it on ``sys.path``. This can be as 717 simple as:: 718 719 from pkg_resources import require 720 require("SomePackage", "OtherPackage", "MyPackage") 721 722 which will put the latest installed version of the specified packages on 723 ``sys.path`` for you. (For more advanced uses, like selecting specific 724 versions and enabling optional dependencies, see the ``pkg_resources`` API 725 doc.) 726 727 Changed in 0.6a10: this option is no longer silently enabled when 728 installing to a non-PYTHONPATH, non-"site" directory. You must always 729 explicitly use this option if you want it to be active. 730 731``--upgrade, -U`` (New in 0.5a4) 732 By default, EasyInstall only searches online if a project/version 733 requirement can't be met by distributions already installed 734 on sys.path or the installation directory. However, if you supply the 735 ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package 736 index and ``--find-links`` URLs before selecting a version to install. In 737 this way, you can force EasyInstall to use the latest available version of 738 any package it installs (subject to any version requirements that might 739 exclude such later versions). 740 741``--install-dir=DIR, -d DIR`` 742 Set the installation directory. It is up to you to ensure that this 743 directory is on ``sys.path`` at runtime, and to use 744 ``pkg_resources.require()`` to enable the installed package(s) that you 745 need. 746 747 (New in 0.4a2) If this option is not directly specified on the command line 748 or in a distutils configuration file, the distutils default installation 749 location is used. Normally, this would be the ``site-packages`` directory, 750 but if you are using distutils configuration files, setting things like 751 ``prefix`` or ``install_lib``, then those settings are taken into 752 account when computing the default installation directory, as is the 753 ``--prefix`` option. 754 755``--script-dir=DIR, -s DIR`` 756 Set the script installation directory. If you don't supply this option 757 (via the command line or a configuration file), but you *have* supplied 758 an ``--install-dir`` (via command line or config file), then this option 759 defaults to the same directory, so that the scripts will be able to find 760 their associated package installation. Otherwise, this setting defaults 761 to the location where the distutils would normally install scripts, taking 762 any distutils configuration file settings into account. 763 764``--exclude-scripts, -x`` 765 Don't install scripts. This is useful if you need to install multiple 766 versions of a package, but do not want to reset the version that will be 767 run by scripts that are already installed. 768 769``--user`` (New in 0.6.11) 770 Use the user-site-packages as specified in :pep:`370` 771 instead of the global site-packages. 772 773``--always-copy, -a`` (New in 0.5a4) 774 Copy all needed distributions to the installation directory, even if they 775 are already present in a directory on sys.path. In older versions of 776 EasyInstall, this was the default behavior, but now you must explicitly 777 request it. By default, EasyInstall will no longer copy such distributions 778 from other sys.path directories to the installation directory, unless you 779 explicitly gave the distribution's filename on the command line. 780 781 Note that as of 0.6a10, using this option excludes "system" and 782 "development" eggs from consideration because they can't be reliably 783 copied. This may cause EasyInstall to choose an older version of a package 784 than what you expected, or it may cause downloading and installation of a 785 fresh copy of something that's already installed. You will see warning 786 messages for any eggs that EasyInstall skips, before it falls back to an 787 older version or attempts to download a fresh copy. 788 789``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES`` 790 Scan the specified "download pages" or directories for direct links to eggs 791 or other distributions. Any existing file or directory names or direct 792 download URLs are immediately added to EasyInstall's search cache, and any 793 indirect URLs (ones that don't point to eggs or other recognized archive 794 formats) are added to a list of additional places to search for download 795 links. As soon as EasyInstall has to go online to find a package (either 796 because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was 797 used), the specified URLs will be downloaded and scanned for additional 798 direct links. 799 800 Eggs and archives found by way of ``--find-links`` are only downloaded if 801 they are needed to meet a requirement specified on the command line; links 802 to unneeded packages are ignored. 803 804 If all requested packages can be found using links on the specified 805 download pages, the Python Package Index will not be consulted unless you 806 also specified the ``--upgrade`` or ``-U`` option. 807 808 (Note: if you want to refer to a local HTML file containing links, you must 809 use a ``file:`` URL, as filenames that do not refer to a directory, egg, or 810 archive are ignored.) 811 812 You may specify multiple URLs or file/directory names with this option, 813 separated by whitespace. Note that on the command line, you will probably 814 have to surround the URL list with quotes, so that it is recognized as a 815 single option value. You can also specify URLs in a configuration file; 816 see `Configuration Files`_, above. 817 818 Changed in 0.6a10: previously all URLs and directories passed to this 819 option were scanned as early as possible, but from 0.6a10 on, only 820 directories and direct archive links are scanned immediately; URLs are not 821 retrieved unless a package search was already going to go online due to a 822 package not being available locally, or due to the use of the ``--update`` 823 or ``-U`` option. 824 825``--no-find-links`` Blocks the addition of any link. 826 This parameter is useful if you want to avoid adding links defined in a 827 project easy_install is installing (whether it's a requested project or a 828 dependency). When used, ``--find-links`` is ignored. 829 830 Added in Distribute 0.6.11 and Setuptools 0.7. 831 832``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7) 833 Specifies the base URL of the Python Package Index. The default is 834 https://pypi.org/simple/ if not specified. When a package is requested 835 that is not locally available or linked from a ``--find-links`` download 836 page, the package index will be searched for download pages for the needed 837 package, and those download pages will be searched for links to download 838 an egg or source distribution. 839 840``--editable, -e`` (New in 0.6a1) 841 Only find and download source distributions for the specified projects, 842 unpacking them to subdirectories of the specified ``--build-directory``. 843 EasyInstall will not actually build or install the requested projects or 844 their dependencies; it will just find and extract them for you. See 845 `Editing and Viewing Source Packages`_ above for more details. 846 847``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1) 848 Set the directory used to build source packages. If a package is built 849 from a source distribution or checkout, it will be extracted to a 850 subdirectory of the specified directory. The subdirectory will have the 851 same name as the extracted distribution's project, but in all-lowercase. 852 If a file or directory of that name already exists in the given directory, 853 a warning will be printed to the console, and the build will take place in 854 a temporary directory instead. 855 856 This option is most useful in combination with the ``--editable`` option, 857 which forces EasyInstall to *only* find and extract (but not build and 858 install) source distributions. See `Editing and Viewing Source Packages`_, 859 above, for more information. 860 861``--verbose, -v, --quiet, -q`` (New in 0.4a4) 862 Control the level of detail of EasyInstall's progress messages. The 863 default detail level is "info", which prints information only about 864 relatively time-consuming operations like running a setup script, unpacking 865 an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the 866 detail level to "warn", which will only display installation reports, 867 warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail 868 level to include individual file-level operations, link analysis messages, 869 and distutils messages from any setup scripts that get run. If you include 870 the ``-v`` option more than once, the second and subsequent uses are passed 871 down to any setup scripts, increasing the verbosity of their reporting as 872 well. 873 874``--dry-run, -n`` (New in 0.4a4) 875 Don't actually install the package or scripts. This option is passed down 876 to any setup scripts run, so packages should not actually build either. 877 This does *not* skip downloading, nor does it skip extracting source 878 distributions to a temporary/build directory. 879 880``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4) 881 If you are installing from a source distribution, and are *not* using the 882 ``--zip-ok`` option, this option controls the optimization level for 883 compiling installed ``.py`` files to ``.pyo`` files. It does not affect 884 the compilation of modules contained in ``.egg`` files, only those in 885 ``.egg`` directories. The optimization level can be set to 0, 1, or 2; 886 the default is 0 (unless it's set under ``install`` or ``install_lib`` in 887 one of your distutils configuration files). 888 889``--record=FILENAME`` (New in 0.5a4) 890 Write a record of all installed files to FILENAME. This is basically the 891 same as the same option for the standard distutils "install" command, and 892 is included for compatibility with tools that expect to pass this option 893 to "setup.py install". 894 895``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1) 896 Specify one or more custom "site" directories (separated by commas). 897 "Site" directories are directories where ``.pth`` files are processed, such 898 as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall 899 automatically detects whether a given directory processes ``.pth`` files 900 (or can be made to do so), so you should not normally need to use this 901 option. It is is now only necessary if you want to override EasyInstall's 902 judgment and force an installation directory to be treated as if it 903 supported ``.pth`` files. 904 905``--no-deps, -N`` (New in 0.6a6) 906 Don't install any dependencies. This is intended as a convenience for 907 tools that wrap eggs in a platform-specific packaging system. (We don't 908 recommend that you use it for anything else.) 909 910``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6) 911 Restrict downloading and spidering to hosts matching the specified glob 912 patterns. E.g. ``-H *.python.org`` restricts web access so that only 913 packages listed and downloadable from machines in the ``python.org`` 914 domain. The glob patterns must match the *entire* user/host/port section of 915 the target URL(s). For example, ``*.python.org`` will NOT accept a URL 916 like ``http://python.org/foo`` or ``http://www.python.org:8080/``. 917 Multiple patterns can be specified by separating them with commas. The 918 default pattern is ``*``, which matches anything. 919 920 In general, this option is mainly useful for blocking EasyInstall's web 921 access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet 922 or other trusted site. EasyInstall will do the best it can to satisfy 923 dependencies given your host restrictions, but of course can fail if it 924 can't find suitable packages. EasyInstall displays all blocked URLs, so 925 that you can adjust your ``--allow-hosts`` setting if it is more strict 926 than you intended. Some sites may wish to define a restrictive default 927 setting for this option in their `configuration files`_, and then manually 928 override the setting on the command line as needed. 929 930``--prefix=DIR`` (New in 0.6a10) 931 Use the specified directory as a base for computing the default 932 installation and script directories. On Windows, the resulting default 933 directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``, 934 while on other platforms the defaults will be 935 ``prefix/lib/python2.X/site-packages`` (with the appropriate version 936 substituted) for libraries and ``prefix/bin`` for scripts. 937 938 Note that the ``--prefix`` option only sets the *default* installation and 939 script directories, and does not override the ones set on the command line 940 or in a configuration file. 941 942``--local-snapshots-ok, -l`` (New in 0.6c6) 943 Normally, EasyInstall prefers to only install *released* versions of 944 projects, not in-development ones, because such projects may not 945 have a currently-valid version number. So, it usually only installs them 946 when their ``setup.py`` directory is explicitly passed on the command line. 947 948 However, if this option is used, then any in-development projects that were 949 installed using the ``setup.py develop`` command, will be used to build 950 eggs, effectively upgrading the "in-development" project to a snapshot 951 release. Normally, this option is used only in conjunction with the 952 ``--always-copy`` option to create a distributable snapshot of every egg 953 needed to run an application. 954 955 Note that if you use this option, you must make sure that there is a valid 956 version number (such as an SVN revision number tag) for any in-development 957 projects that may be used, as otherwise EasyInstall may not be able to tell 958 what version of the project is "newer" when future installations or 959 upgrades are attempted. 960 961 962.. _non-root installation: 963 964Custom Installation Locations 965----------------------------- 966 967By default, EasyInstall installs python packages into Python's main ``site-packages`` directory, 968and manages them using a custom ``.pth`` file in that same directory. 969 970Very often though, a user or developer wants ``easy_install`` to install and manage python packages 971in an alternative location, usually for one of 3 reasons: 972 9731. They don't have access to write to the main Python site-packages directory. 974 9752. They want a user-specific stash of packages, that is not visible to other users. 976 9773. They want to isolate a set of packages to a specific python application, usually to minimize 978 the possibility of version conflicts. 979 980Historically, there have been many approaches to achieve custom installation. 981The following section lists only the easiest and most relevant approaches [1]_. 982 983`Use the "--user" option`_ 984 985`Use the "--user" option and customize "PYTHONUSERBASE"`_ 986 987`Use "virtualenv"`_ 988 989.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_. 990 991.. _PEP-370: http://www.python.org/dev/peps/pep-0370/ 992 993 994Use the "--user" option 995~~~~~~~~~~~~~~~~~~~~~~~ 996Python provides a User scheme for installation, which means that all 997python distributions support an alternative install location that is specific to a user [3]_. 998The Default location for each OS is explained in the python documentation 999for the ``site.USER_BASE`` variable. This mode of installation can be turned on by 1000specifying the ``--user`` option to ``setup.py install`` or ``easy_install``. 1001This approach serves the need to have a user-specific stash of packages. 1002 1003.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized. 1004 1005Use the "--user" option and customize "PYTHONUSERBASE" 1006~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1007The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment 1008variable, which updates the value of ``site.USER_BASE``. To isolate packages to a specific 1009application, simply set the OS environment of that application to a specific value of 1010``PYTHONUSERBASE``, that contains just those packages. 1011 1012Use "virtualenv" 1013~~~~~~~~~~~~~~~~ 1014"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby 1015creating an isolated location to install packages. The evolution of "virtualenv" started before the existence 1016of the User installation scheme. "virtualenv" provides a version of ``easy_install`` that is 1017scoped to the cloned python install and is used in the normal way. "virtualenv" does offer various features 1018that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages. 1019 1020Please refer to the `virtualenv`_ documentation for more details. 1021 1022.. _virtualenv: https://pypi.org/project/virtualenv/ 1023 1024 1025 1026Package Index "API" 1027------------------- 1028 1029Custom package indexes (and PyPI) must follow the following rules for 1030EasyInstall to be able to look up and download packages: 1031 10321. Except where stated otherwise, "pages" are HTML or XHTML, and "links" 1033 refer to ``href`` attributes. 1034 10352. Individual project version pages' URLs must be of the form 1036 ``base/projectname/version``, where ``base`` is the package index's base URL. 1037 10383. Omitting the ``/version`` part of a project page's URL (but keeping the 1039 trailing ``/``) should result in a page that is either: 1040 1041 a) The single active version of that project, as though the version had been 1042 explicitly included, OR 1043 1044 b) A page with links to all of the active version pages for that project. 1045 10464. Individual project version pages should contain direct links to downloadable 1047 distributions where possible. It is explicitly permitted for a project's 1048 "long_description" to include URLs, and these should be formatted as HTML 1049 links by the package index, as EasyInstall does no special processing to 1050 identify what parts of a page are index-specific and which are part of the 1051 project's supplied description. 1052 10535. Where available, MD5 information should be added to download URLs by 1054 appending a fragment identifier of the form ``#md5=...``, where ``...`` is 1055 the 32-character hex MD5 digest. EasyInstall will verify that the 1056 downloaded file's MD5 digest matches the given value. 1057 10586. Individual project version pages should identify any "homepage" or 1059 "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes 1060 on the HTML elements linking to those URLs. Use of these attributes will 1061 cause EasyInstall to always follow the provided links, unless it can be 1062 determined by inspection that they are downloadable distributions. If the 1063 links are not to downloadable distributions, they are retrieved, and if they 1064 are HTML, they are scanned for download links. They are *not* scanned for 1065 additional "homepage" or "download" links, as these are only processed for 1066 pages that are part of a package index site. 1067 10687. The root URL of the index, if retrieved with a trailing ``/``, must result 1069 in a page containing links to *all* projects' active version pages. 1070 1071 (Note: This requirement is a workaround for the absence of case-insensitive 1072 ``safe_name()`` matching of project names in URL paths. If project names are 1073 matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar 1074 mechanism), then it is not necessary to include this all-packages listing 1075 page.) 1076 10778. If a package index is accessed via a ``file://`` URL, then EasyInstall will 1078 automatically use ``index.html`` files, if present, when trying to read a 1079 directory with a trailing ``/`` on the URL. 1080 1081 1082Backward Compatibility 1083~~~~~~~~~~~~~~~~~~~~~~ 1084 1085Package indexes that wish to support setuptools versions prior to 0.6b4 should 1086also follow these rules: 1087 1088* Homepage and download links must be preceded with ``"<th>Home Page"`` or 1089 ``"<th>Download URL"``, in addition to (or instead of) the ``rel=""`` 1090 attributes on the actual links. These marker strings do not need to be 1091 visible, or uncommented, however! For example, the following is a valid 1092 homepage link that will work with any version of setuptools:: 1093 1094 <li> 1095 <strong>Home Page:</strong> 1096 <!-- <th>Home Page --> 1097 <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a> 1098 </li> 1099 1100 Even though the marker string is in an HTML comment, older versions of 1101 EasyInstall will still "see" it and know that the link that follows is the 1102 project's home page URL. 1103 1104* The pages described by paragraph 3(b) of the preceding section *must* 1105 contain the string ``"Index of Packages</title>"`` somewhere in their text. 1106 This can be inside of an HTML comment, if desired, and it can be anywhere 1107 in the page. (Note: this string MUST NOT appear on normal project pages, as 1108 described in paragraphs 2 and 3(a)!) 1109 1110In addition, for compatibility with PyPI versions that do not use ``#md5=`` 1111fragment IDs, EasyInstall uses the following regular expression to match PyPI's 1112displayed MD5 info (broken onto two lines for readability):: 1113 1114 <a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5 1115 &digest=([0-9a-f]{32})">md5</a>\) 1116 1117History 1118======= 1119 11200.6c9 1121 * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting 1122 is flattened out in the resulting egg. (There was a case-sensitivity 1123 problem that affected some distributions, notably ``pywin32``.) 1124 1125 * Prevent ``--help-commands`` and other junk from showing under Python 2.5 1126 when running ``easy_install --help``. 1127 1128 * Fixed GUI scripts sometimes not executing on Windows 1129 1130 * Fixed not picking up dependency links from recursive dependencies. 1131 1132 * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs 1133 1134 * Changes for Jython compatibility 1135 1136 * Improved error message when a requirement is also a directory name, but the 1137 specified directory is not a source package. 1138 1139 * Fixed ``--allow-hosts`` option blocking ``file:`` URLs 1140 1141 * Fixed HTTP SVN detection failing when the page title included a project 1142 name (e.g. on SourceForge-hosted SVN) 1143 1144 * Fix Jython script installation to handle ``#!`` lines better when 1145 ``sys.executable`` is a script. 1146 1147 * Removed use of deprecated ``md5`` module if ``hashlib`` is available 1148 1149 * Keep site directories (e.g. ``site-packages``) from being included in 1150 ``.pth`` files. 1151 11520.6c7 1153 * ``ftp:`` download URLs now work correctly. 1154 1155 * The default ``--index-url`` is now ``https://pypi.python.org/simple``, to use 1156 the Python Package Index's new simpler (and faster!) REST API. 1157 11580.6c6 1159 * EasyInstall no longer aborts the installation process if a URL it wants to 1160 retrieve can't be downloaded, unless the URL is an actual package download. 1161 Instead, it issues a warning and tries to keep going. 1162 1163 * Fixed distutils-style scripts originally built on Windows having their line 1164 endings doubled when installed on any platform. 1165 1166 * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects 1167 installed using ``setup.py develop``. 1168 1169 * Fixed not HTML-decoding URLs scraped from web pages 1170 11710.6c5 1172 * Fixed ``.dll`` files on Cygwin not having executable permissions when an egg 1173 is installed unzipped. 1174 11750.6c4 1176 * Added support for HTTP "Basic" authentication using ``http://user:pass@host`` 1177 URLs. If a password-protected page contains links to the same host (and 1178 protocol), those links will inherit the credentials used to access the 1179 original page. 1180 1181 * Removed all special support for Sourceforge mirrors, as Sourceforge's 1182 mirror system now works well for non-browser downloads. 1183 1184 * Fixed not recognizing ``win32.exe`` installers that included a custom 1185 bitmap. 1186 1187 * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they 1188 are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as 1189 is done by ``os.urandom()`` on some platforms). 1190 1191 * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable`` 1192 has a space in it (e.g., the user installed Python to a ``Program Files`` 1193 directory). 1194 11950.6c3 1196 * You can once again use "python -m easy_install" with Python 2.4 and above. 1197 1198 * Python 2.5 compatibility fixes added. 1199 12000.6c2 1201 * Windows script wrappers now support quoted arguments and arguments 1202 containing spaces. (Patch contributed by Jim Fulton.) 1203 1204 * The ``ez_setup.py`` script now actually works when you put a setuptools 1205 ``.egg`` alongside it for bootstrapping an offline machine. 1206 1207 * A writable installation directory on ``sys.path`` is no longer required to 1208 download and extract a source distribution using ``--editable``. 1209 1210 * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable`` 1211 contains non-ASCII characters, to prevent deprecation warnings about an 1212 unspecified encoding when the script is run. 1213 12140.6c1 1215 * EasyInstall now includes setuptools version information in the 1216 ``User-Agent`` string sent to websites it visits. 1217 12180.6b4 1219 * Fix creating Python wrappers for non-Python scripts 1220 1221 * Fix ``ftp://`` directory listing URLs from causing a crash when used in the 1222 "Home page" or "Download URL" slots on PyPI. 1223 1224 * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile 1225 or directory is deleted/overwritten. 1226 1227 * Fix not recognizing HTML 404 pages from package indexes. 1228 1229 * Allow ``file://`` URLs to be used as a package index. URLs that refer to 1230 directories will use an internally-generated directory listing if there is 1231 no ``index.html`` file in the directory. 1232 1233 * Allow external links in a package index to be specified using 1234 ``rel="homepage"`` or ``rel="download"``, without needing the old 1235 PyPI-specific visible markup. 1236 1237 * Suppressed warning message about possibly-misspelled project name, if an egg 1238 or link for that project name has already been seen. 1239 12400.6b3 1241 * Fix local ``--find-links`` eggs not being copied except with 1242 ``--always-copy``. 1243 1244 * Fix sometimes not detecting local packages installed outside of "site" 1245 directories. 1246 1247 * Fix mysterious errors during initial ``setuptools`` install, caused by 1248 ``ez_setup`` trying to run ``easy_install`` twice, due to a code fallthru 1249 after deleting the egg from which it's running. 1250 12510.6b2 1252 * Don't install or update a ``site.py`` patch when installing to a 1253 ``PYTHONPATH`` directory with ``--multi-version``, unless an 1254 ``easy-install.pth`` file is already in use there. 1255 1256 * Construct ``.pth`` file paths in such a way that installing an egg whose 1257 name begins with ``import`` doesn't cause a syntax error. 1258 1259 * Fixed a bogus warning message that wasn't updated since the 0.5 versions. 1260 12610.6b1 1262 * Better ambiguity management: accept ``#egg`` name/version even if processing 1263 what appears to be a correctly-named distutils file, and ignore ``.egg`` 1264 files with no ``-``, since valid Python ``.egg`` files always have a version 1265 number (but Scheme eggs often don't). 1266 1267 * Support ``file://`` links to directories in ``--find-links``, so that 1268 easy_install can build packages from local source checkouts. 1269 1270 * Added automatic retry for Sourceforge mirrors. The new download process is 1271 to first just try dl.sourceforge.net, then randomly select mirror IPs and 1272 remove ones that fail, until something works. The removed IPs stay removed 1273 for the remainder of the run. 1274 1275 * Ignore bdist_dumb distributions when looking at download URLs. 1276 12770.6a11 1278 * Process ``dependency_links.txt`` if found in a distribution, by adding the 1279 URLs to the list for scanning. 1280 1281 * Use relative paths in ``.pth`` files when eggs are being installed to the 1282 same directory as the ``.pth`` file. This maximizes portability of the 1283 target directory when building applications that contain eggs. 1284 1285 * Added ``easy_install-N.N`` script(s) for convenience when using multiple 1286 Python versions. 1287 1288 * Added automatic handling of installation conflicts. Eggs are now shifted to 1289 the front of sys.path, in an order consistent with where they came from, 1290 making EasyInstall seamlessly co-operate with system package managers. 1291 1292 The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options 1293 are now no longer necessary, and will generate warnings at the end of a 1294 run if you use them. 1295 1296 * Don't recursively traverse subdirectories given to ``--find-links``. 1297 12980.6a10 1299 * Added exhaustive testing of the install directory, including a spawn test 1300 for ``.pth`` file support, and directory writability/existence checks. This 1301 should virtually eliminate the need to set or configure ``--site-dirs``. 1302 1303 * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of 1304 RTFM-ing. :) 1305 1306 * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it 1307 manually to make it work. ``--multi-version`` is no longer a silent 1308 default; you must explicitly use it if installing to a non-PYTHONPATH, 1309 non-"site" directory. 1310 1311 * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``, 1312 ``--install-dir``, and ``--script-dir`` options, whether on the command line 1313 or in configuration files. 1314 1315 * Improved SourceForge mirror processing to work faster and be less affected 1316 by transient HTML changes made by SourceForge. 1317 1318 * PyPI searches now use the exact spelling of requirements specified on the 1319 command line or in a project's ``install_requires``. Previously, a 1320 normalized form of the name was used, which could lead to unnecessary 1321 full-index searches when a project's name had an underscore (``_``) in it. 1322 1323 * EasyInstall can now download bare ``.py`` files and wrap them in an egg, 1324 as long as you include an ``#egg=name-version`` suffix on the URL, or if 1325 the ``.py`` file is listed as the "Download URL" on the project's PyPI page. 1326 This allows third parties to "package" trivial Python modules just by 1327 linking to them (e.g. from within their own PyPI page or download links 1328 page). 1329 1330 * The ``--always-copy`` option now skips "system" and "development" eggs since 1331 they can't be reliably copied. Note that this may cause EasyInstall to 1332 choose an older version of a package than what you expected, or it may cause 1333 downloading and installation of a fresh version of what's already installed. 1334 1335 * The ``--find-links`` option previously scanned all supplied URLs and 1336 directories as early as possible, but now only directories and direct 1337 archive links are scanned immediately. URLs are not retrieved unless a 1338 package search was already going to go online due to a package not being 1339 available locally, or due to the use of the ``--update`` or ``-U`` option. 1340 1341 * Fixed the annoying ``--help-commands`` wart. 1342 13430.6a9 1344 * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside 1345 "baskets") when they weren't explicitly listed in the ``.pth`` file. 1346 1347 * If more than one URL appears to describe the exact same distribution, prefer 1348 the shortest one. This helps to avoid "table of contents" CGI URLs like the 1349 ones on effbot.org. 1350 1351 * Quote arguments to python.exe (including python's path) to avoid problems 1352 when Python (or a script) is installed in a directory whose name contains 1353 spaces on Windows. 1354 1355 * Support full roundtrip translation of eggs to and from ``bdist_wininst`` 1356 format. Running ``bdist_wininst`` on a setuptools-based package wraps the 1357 egg in an .exe that will safely install it as an egg (i.e., with metadata 1358 and entry-point wrapper scripts), and ``easy_install`` can turn the .exe 1359 back into an ``.egg`` file or directory and install it as such. 1360 13610.6a8 1362 * Update for changed SourceForge mirror format 1363 1364 * Fixed not installing dependencies for some packages fetched via Subversion 1365 1366 * Fixed dependency installation with ``--always-copy`` not using the same 1367 dependency resolution procedure as other operations. 1368 1369 * Fixed not fully removing temporary directories on Windows, if a Subversion 1370 checkout left read-only files behind 1371 1372 * Fixed some problems building extensions when Pyrex was installed, especially 1373 with Python 2.4 and/or packages using SWIG. 1374 13750.6a7 1376 * Fixed not being able to install Windows script wrappers using Python 2.3 1377 13780.6a6 1379 * Added support for "traditional" PYTHONPATH-based non-root installation, and 1380 also the convenient ``virtual-python.py`` script, based on a contribution 1381 by Ian Bicking. The setuptools egg now contains a hacked ``site`` module 1382 that makes the PYTHONPATH-based approach work with .pth files, so that you 1383 can get the full EasyInstall feature set on such installations. 1384 1385 * Added ``--no-deps`` and ``--allow-hosts`` options. 1386 1387 * Improved Windows ``.exe`` script wrappers so that the script can have the 1388 same name as a module without confusing Python. 1389 1390 * Changed dependency processing so that it's breadth-first, allowing a 1391 depender's preferences to override those of a dependee, to prevent conflicts 1392 when a lower version is acceptable to the dependee, but not the depender. 1393 Also, ensure that currently installed/selected packages aren't given 1394 precedence over ones desired by a package being installed, which could 1395 cause conflict errors. 1396 13970.6a3 1398 * Improved error message when trying to use old ways of running 1399 ``easy_install``. Removed the ability to run via ``python -m`` or by 1400 running ``easy_install.py``; ``easy_install`` is the command to run on all 1401 supported platforms. 1402 1403 * Improved wrapper script generation and runtime initialization so that a 1404 VersionConflict doesn't occur if you later install a competing version of a 1405 needed package as the default version of that package. 1406 1407 * Fixed a problem parsing version numbers in ``#egg=`` links. 1408 14090.6a2 1410 * EasyInstall can now install "console_scripts" defined by packages that use 1411 ``setuptools`` and define appropriate entry points. On Windows, console 1412 scripts get an ``.exe`` wrapper so you can just type their name. On other 1413 platforms, the scripts are installed without a file extension. 1414 1415 * Using ``python -m easy_install`` or running ``easy_install.py`` is now 1416 DEPRECATED, since an ``easy_install`` wrapper is now available on all 1417 platforms. 1418 14190.6a1 1420 * EasyInstall now does MD5 validation of downloads from PyPI, or from any link 1421 that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest. 1422 1423 * EasyInstall now handles symlinks in target directories by removing the link, 1424 rather than attempting to overwrite the link's destination. This makes it 1425 easier to set up an alternate Python "home" directory (as described above in 1426 the `Non-Root Installation`_ section). 1427 1428 * Added support for handling MacOS platform information in ``.egg`` filenames, 1429 based on a contribution by Kevin Dangoor. You may wish to delete and 1430 reinstall any eggs whose filename includes "darwin" and "Power_Macintosh", 1431 because the format for this platform information has changed so that minor 1432 OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a 1433 previous OS version to become obsolete. 1434 1435 * easy_install's dependency processing algorithms have changed. When using 1436 ``--always-copy``, it now ensures that dependencies are copied too. When 1437 not using ``--always-copy``, it tries to use a single resolution loop, 1438 rather than recursing. 1439 1440 * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py`` 1441 extensions. 1442 1443 * Added ``--site-dirs`` option to allow adding custom "site" directories. 1444 Made ``easy-install.pth`` work in platform-specific alternate site 1445 directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X). 1446 1447 * If you manually delete the current version of a package, the next run of 1448 EasyInstall against the target directory will now remove the stray entry 1449 from the ``easy-install.pth`` file. 1450 1451 * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID 1452 as pointing to the named project's source checkout. Such URLs have a lower 1453 match precedence than any other kind of distribution, so they'll only be 1454 used if they have a higher version number than any other available 1455 distribution, or if you use the ``--editable`` option. The ``#egg`` 1456 fragment can contain a version if it's formatted as ``#egg=proj-ver``, 1457 where ``proj`` is the project name, and ``ver`` is the version number. You 1458 *must* use the format for these values that the ``bdist_egg`` command uses; 1459 i.e., all non-alphanumeric runs must be condensed to single underscore 1460 characters. 1461 1462 * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_ 1463 above for more info. Also, slightly changed the behavior of the 1464 ``--build-directory`` option. 1465 1466 * Fixed the setup script sandbox facility not recognizing certain paths as 1467 valid on case-insensitive platforms. 1468 14690.5a12 1470 * Fix ``python -m easy_install`` not working due to setuptools being installed 1471 as a zipfile. Update safety scanner to check for modules that might be used 1472 as ``python -m`` scripts. 1473 1474 * Misc. fixes for win32.exe support, including changes to support Python 2.4's 1475 changed ``bdist_wininst`` format. 1476 14770.5a10 1478 * Put the ``easy_install`` module back in as a module, as it's needed for 1479 ``python -m`` to run it! 1480 1481 * Allow ``--find-links/-f`` to accept local directories or filenames as well 1482 as URLs. 1483 14840.5a9 1485 * EasyInstall now automatically detects when an "unmanaged" package or 1486 module is going to be on ``sys.path`` ahead of a package you're installing, 1487 thereby preventing the newer version from being imported. By default, it 1488 will abort installation to alert you of the problem, but there are also 1489 new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``) 1490 available to change the default behavior. (Note: this new feature doesn't 1491 take effect for egg files that were built with older ``setuptools`` 1492 versions, because they lack the new metadata file required to implement it.) 1493 1494 * The ``easy_install`` distutils command now uses ``DistutilsError`` as its 1495 base error type for errors that should just issue a message to stderr and 1496 exit the program without a traceback. 1497 1498 * EasyInstall can now be given a path to a directory containing a setup 1499 script, and it will attempt to build and install the package there. 1500 1501 * EasyInstall now performs a safety analysis on module contents to determine 1502 whether a package is likely to run in zipped form, and displays 1503 information about what modules may be doing introspection that would break 1504 when running as a zipfile. 1505 1506 * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that 1507 would ordinarily be considered safe to unzip, and changed the meaning of 1508 ``--zip-ok/-z`` to "always leave everything zipped". 1509 15100.5a8 1511 * There is now a separate documentation page for `setuptools`_; revision 1512 history that's not specific to EasyInstall has been moved to that page. 1513 1514 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools 1515 15160.5a5 1517 * Made ``easy_install`` a standard ``setuptools`` command, moving it from 1518 the ``easy_install`` module to ``setuptools.command.easy_install``. Note 1519 that if you were importing or extending it, you must now change your imports 1520 accordingly. ``easy_install.py`` is still installed as a script, but not as 1521 a module. 1522 15230.5a4 1524 * Added ``--always-copy/-a`` option to always copy needed packages to the 1525 installation directory, even if they're already present elsewhere on 1526 sys.path. (In previous versions, this was the default behavior, but now 1527 you must request it.) 1528 1529 * Added ``--upgrade/-U`` option to force checking PyPI for latest available 1530 version(s) of all packages requested by name and version, even if a matching 1531 version is available locally. 1532 1533 * Added automatic installation of dependencies declared by a distribution 1534 being installed. These dependencies must be listed in the distribution's 1535 ``EGG-INFO`` directory, so the distribution has to have declared its 1536 dependencies by using setuptools. If a package has requirements it didn't 1537 declare, you'll still have to deal with them yourself. (E.g., by asking 1538 EasyInstall to find and install them.) 1539 1540 * Added the ``--record`` option to ``easy_install`` for the benefit of tools 1541 that run ``setup.py install --record=filename`` on behalf of another 1542 packaging system.) 1543 15440.5a3 1545 * Fixed not setting script permissions to allow execution. 1546 1547 * Improved sandboxing so that setup scripts that want a temporary directory 1548 (e.g. pychecker) can still run in the sandbox. 1549 15500.5a2 1551 * Fix stupid stupid refactoring-at-the-last-minute typos. :( 1552 15530.5a1 1554 * Added support for converting ``.win32.exe`` installers to eggs on the fly. 1555 EasyInstall will now recognize such files by name and install them. 1556 1557 * Fixed a problem with picking the "best" version to install (versions were 1558 being sorted as strings, rather than as parsed values) 1559 15600.4a4 1561 * Added support for the distutils "verbose/quiet" and "dry-run" options, as 1562 well as the "optimize" flag. 1563 1564 * Support downloading packages that were uploaded to PyPI (by scanning all 1565 links on package pages, not just the homepage/download links). 1566 15670.4a3 1568 * Add progress messages to the search/download process so that you can tell 1569 what URLs it's reading to find download links. (Hopefully, this will help 1570 people report out-of-date and broken links to package authors, and to tell 1571 when they've asked for a package that doesn't exist.) 1572 15730.4a2 1574 * Added support for installing scripts 1575 1576 * Added support for setting options via distutils configuration files, and 1577 using distutils' default options as a basis for EasyInstall's defaults. 1578 1579 * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the 1580 script installation directory option. 1581 1582 * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if 1583 Python includes SSL support. 1584 15850.4a1 1586 * Added ``--scan-url`` and ``--index-url`` options, to scan download pages 1587 and search PyPI for needed packages. 1588 15890.3a4 1590 * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single 1591 URL installs, to avoid running the wrong setup.py. 1592 15930.3a3 1594 * Added ``--build-directory=DIR/-b DIR`` option. 1595 1596 * Added "installation report" that explains how to use 'require()' when doing 1597 a multiversion install or alternate installation directory. 1598 1599 * Added SourceForge mirror auto-select (Contributed by Ian Bicking) 1600 1601 * Added "sandboxing" that stops a setup script from running if it attempts to 1602 write to the filesystem outside of the build area 1603 1604 * Added more workarounds for packages with quirky ``install_data`` hacks 1605 16060.3a2 1607 * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as 1608 automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking) 1609 1610 * Misc. bug fixes 1611 16120.3a1 1613 * Initial release. 1614 1615 1616Future Plans 1617============ 1618 1619* Additional utilities to list/remove/verify packages 1620* Signature checking? SSL? Ability to suppress PyPI search? 1621* Display byte progress meter when downloading distributions and long pages? 1622* Redirect stdout/stderr to log during run_setup? 1623