Please see the setuptools on the package index for download links and basic installation instructions for each of the supported platforms.
You will need at least Python 3.5 or 2.7. 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 installing to Python’s primary site-packages directory. If this is not the case, you should consult the section below on Custom Installation Locations before installing. (And, on Windows, you should not use the .exe installer when installing to an alternate location.)
Note that easy_install normally works by downloading files from the internet. If you are behind an NTLM-based firewall that prevents Python programs from accessing the net directly, you may wish to first install and use the APS proxy server, which lets you get past such firewalls in the same way that your web browser(s) do.
(Alternately, if you do not wish easy_install to actually download anything, you can restrict it from doing so with the --allow-hosts option; see the sections on restricting downloads with –allow-hosts and command-line options for more details.)
Troubleshooting¶If EasyInstall/setuptools appears to install correctly, and you can run the easy_install command but it fails with an ImportError, the most likely cause is that you installed to a location other than site-packages, without taking any of the steps described in the Custom Installation Locations section below. Please see that section and follow the steps to make sure that your custom location will work correctly. Then re-install.
Similarly, if you can run easy_install, and it appears to be installing packages, but then you can’t import them, the most likely issue is that you installed EasyInstall correctly but are using it to install packages to a non-standard location that hasn’t been properly prepared. Again, see the section on Custom Installation Locations for more details.
Windows Notes¶Installing setuptools will provide an easy_install command according to the techniques described in Executables and Launchers. If the easy_install command is not ailable after installation, that section provides details on how to configure Windows to make the commands ailable.
Downloading and Installing a Package¶For basic use of easy_install, you need only supply the filename or URL of a source distribution or .egg file (Python Egg).
Example 1. Install a package by name, searching PyPI for the latest version, and automatically downloading, building, and installing it:
easy_install SQLObjectExample 2. Install or upgrade a package by name and version by finding links on a given “download page”:
easy_install -f http://pythonpaste.org/package_index.html SQLObjectExample 3. Download a source distribution from a specified URL, automatically building and installing it:
easy_install http://example.com/path/to/MyPackage-1.2.3.tgzExample 4. Install an already-downloaded .egg file:
easy_install /my_downloads/OtherPackage-3.2.1-py2.3.eggExample 5. Upgrade an already-installed package to the latest version listed on PyPI:
easy_install --upgrade PyProtocolsExample 6. Install a source distribution that’s already downloaded and extracted in the current directory (New in 0.5a9):
easy_install .Example 7. (New in 0.6a1) Find a source distribution or Subversion checkout URL for a package, and extract it or check it out to ~/projects/sqlobject (the name will always be in all-lowercase), where it can be examined or edited. (The package will not be installed, but it can easily be installed with easy_install ~/projects/sqlobject. See Editing and Viewing Source Packages below for more info.):
easy_install --editable --build-directory ~/projects SQLObjectExample 7. (New in 0.6.11) Install a distribution within your home dir:
easy_install --user SQLAlchemyEasy Install accepts URLs, filenames, PyPI package names (i.e., distutils “distribution” names), and package+version specifiers. In each case, it will attempt to locate the latest ailable version that meets your criteria.
When downloading or processing downloaded files, Easy Install recognizes distutils source distribution files with extensions of .tgz, .tar, .tar.gz, .tar.bz2, or .zip. And of course it handles already-built .egg distributions as well as .win32.exe installers built using distutils.
By default, packages are installed to the running Python installation’s site-packages directory, unless you provide the -d or --install-dir option to specify an alternative directory, or specify an alternate location using distutils configuration files. (See Configuration Files, below.)
By default, any scripts included with the package are installed to the running Python installation’s standard script installation location. However, if you specify an installation directory via the command line or a config file, then the default directory for installing scripts will be the same as the package installation directory, to ensure that the script will he access to the installed package. You can override this using the -s or --script-dir option.
Installed packages are added to an easy-install.pth file in the install directory, so that Python will always use the most-recently-installed version of the package. If you would like to be able to select which version to use at runtime, you should use the -m or --multi-version option.
Upgrading a Package¶You don’t need to do anything special to upgrade a package: just install the new version, either by requesting a specific version, e.g.:
easy_install "SomePackage==2.0"a version greater than the one you he now:
easy_install "SomePackage>2.0"using the upgrade flag, to find the latest ailable version on PyPI:
easy_install --upgrade SomePackageor by using a download page, direct download URL, or package filename:
easy_install -f http://example.com/downloads ExamplePackage easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg easy_install my_downloads/ExamplePackage-2.0.tgzIf you’re using -m or --multi-version , using the require() function at runtime automatically selects the newest installed version of a package that meets your version criteria. So, installing a newer version is the only step needed to upgrade such packages.
If you’re installing to a directory on PYTHONPATH, or a configured “site” directory (and not using -m), installing a package automatically replaces any previous version in the easy-install.pth file, so that Python will import the most-recently installed version by default. So, again, installing the newer version is the only upgrade step needed.
If you hen’t suppressed script installation (using --exclude-scripts or -x), then the upgraded version’s scripts will be installed, and they will be automatically patched to require() the corresponding version of the package, so that you can use them even if they are installed in multi-version mode.
easy_install never actually deletes packages (unless you’re installing a package with the same name and version number as an existing package), so if you want to get rid of older versions of a package, please see Uninstalling Packages, below.
Changing the Active Version¶If you’ve upgraded a package, but need to revert to a previously-installed version, you can do so like this:
easy_install PackageName==1.2.3Where 1.2.3 is replaced by the exact version number you wish to switch to. If a package matching the requested name and version is not already installed in a directory on sys.path, it will be located via PyPI and installed.
If you’d like to switch to the latest installed version of PackageName, you can do so like this:
easy_install PackageNameThis will activate the latest installed version. (Note: if you he set any find_links via distutils configuration files, those download pages will be checked for the latest ailable version of the package, and it will be downloaded and installed if it is newer than your current version.)
Note that changing the active version of a package will install the newly active version’s scripts, unless the --exclude-scripts or -x option is specified.
Uninstalling Packages¶If you he replaced a package with another version, then you can just delete the package(s) you don’t need by deleting the PackageName-versioninfo.egg file or directory (found in the installation directory).
If you want to delete the currently installed version of a package (or all versions of a package), you should first run:
easy_install -m PackageNameThis will ensure that Python doesn’t continue to search for a package you’re planning to remove. After you’ve done this, you can safely delete the .egg files or directories, along with any scripts you wish to remove.
Managing Scripts¶Whenever you install, upgrade, or change versions of a package, EasyInstall automatically installs the scripts for the selected package version, unless you tell it not to with -x or --exclude-scripts. If any scripts in the script directory he the same name, they are overwritten.
Thus, you do not normally need to manually delete scripts for older versions of a package, unless the newer version of the package does not include a script of the same name. However, if you are completely uninstalling a package, you may wish to manually delete its scripts.
EasyInstall’s default behior means that you can normally only run scripts from one version of a package at a time. If you want to keep multiple versions of a script ailable, however, you can simply use the --multi-version or -m option, and rename the scripts that EasyInstall creates. This works because EasyInstall installs scripts as short code stubs that require() the matching version of the package the script came from, so renaming the script has no effect on what it executes.
For example, suppose you want to use two versions of the rst2html tool provided by the docutils package. You might first install one version:
easy_install -m docutils==0.3.9then rename the rst2html.py to r2h_039, and install another version:
easy_install -m docutils==0.3.10This will create another rst2html.py script, this one using docutils version 0.3.10 instead of 0.3.9. You now he two scripts, each using a different version of the package. (Notice that we used -m for both installations, so that Python won’t lock us out of using anything but the most recently-installed version of the package.)
Executables and Launchers¶On Unix systems, scripts are installed with as natural files with a “#!” header and no extension and they launch under the Python version indicated in the header.
On Windows, there is no mechanism to “execute” files without extensions, so EasyInstall provides two techniques to mirror the Unix behior. The behior is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be “executable” (default) or “natural”.
Regardless of the technique used, the script(s) will be installed to a Scripts directory (by default in the Python installation directory). It is recommended for EasyInstall that you ensure this directory is in the PATH environment variable. The easiest way to ensure the Scripts directory is in the PATH is to run Tools\Scripts\win_add2path.py from the Python directory.
Note that instead of changing your PATH to include the Python scripts directory, you can also retarget the installation location for scripts so they go on a directory that’s already on the PATH. For more information see Command-Line Options and Configuration Files. During installation, pass command line options (such as --script-dir) to control where scripts will be installed.
Windows Executable Launcher¶If the “executable” launcher is used, EasyInstall will create a ‘.exe’ launcher of the same name beside each installed script (including easy_install itself). These small .exe files launch the script of the same name using the Python version indicated in the ‘#!’ header.
This behior is currently default. To force the use of executable launchers, set SETUPTOOLS_LAUNCHER to “executable”.
Natural Script Launcher¶EasyInstall also supports deferring to an external launcher such as pylauncher for launching scripts. Enable this experimental functionality by setting the SETUPTOOLS_LAUNCHER environment variable to “natural”. EasyInstall will then install scripts as simple scripts with a .pya (or .pyw) extension appended. If these extensions are associated with the pylauncher and listed in the PATHEXT environment variable, these scripts can then be invoked simply and directly just like any other executable. This behior may become default in a future version.
EasyInstall uses the .pya extension instead of simply the typical ‘.py’ extension. This distinct extension is necessary to prevent Python from treating the scripts as importable modules (where name conflicts exist). Current releases of pylauncher do not yet associate with .pya files by default, but future versions should do so.
Tips & Techniques¶ Multiple Python Versions¶EasyInstall installs itself under two names: easy_install and easy_install-N.N, where N.N is the Python version used to install it. Thus, if you install EasyInstall for both Python 3.2 and 2.7, you can use the easy_install-3.2 or easy_install-2.7 scripts to install packages for the respective Python version.
Setuptools also supplies easy_install as a runnable module which may be invoked using python -m easy_install for any Python with Setuptools installed.
Restricting Downloads with --allow-hosts¶You can use the --allow-hosts (-H) option to restrict what domains EasyInstall will look for links and downloads on. --allow-hosts=None prevents downloading altogether. You can also use wildcards, for example to restrict downloading to hosts in your own intranet. See the section below on Command-Line Options for more details on the --allow-hosts option.
By default, there are no host restrictions in effect, but you can change this default by editing the appropriate configuration files and adding:
[easy_install] allow_hosts = *.myintranet.example.com,*.python.orgThe above example would then allow downloads only from hosts in the python.org and myintranet.example.com domains, unless overridden on the command line.
Installing on Un-networked Machines¶Just copy the eggs or source packages you need to a directory on the target machine, then use the -f or --find-links option to specify that directory’s location. For example:
easy_install -H None -f somedir SomePackagewill attempt to install SomePackage using only eggs and source packages found in somedir and disallowing all remote access. You should of course make sure you he all of SomePackage’s dependencies ailable in somedir.
If you he another machine of the same operating system and library versions (or if the packages aren’t platform-specific), you can create the directory of eggs using a command like this:
easy_install -zmaxd somedir SomePackageThis will tell EasyInstall to put zipped eggs or source packages for SomePackage and all its dependencies into somedir, without creating any scripts or .pth files. You can then copy the contents of somedir to the target machine. (-z means zipped eggs, -m means multi-version, which prevents .pth files from being used, -a means to copy all the eggs needed, even if they’re installed elsewhere on the machine, and -d indicates the directory to place the eggs in.)
You can also build the eggs from local development packages that were installed with the setup.py develop command, by including the -l option, e.g.:
easy_install -zmaxld somedir SomePackageThis will use locally-ailable source distributions to build the eggs.
Packaging Others’ Projects As Eggs¶Need to distribute a package that isn’t published in egg form? You can use EasyInstall to build eggs for a project. You’ll want to use the --zip-ok, --exclude-scripts, and possibly --no-deps options (-z, -x and -N, respectively). Use -d or --install-dir to specify the location where you’d like the eggs placed. By placing them in a directory that is published to the web, you can then make the eggs ailable for download, either in an intranet or to the internet at large.
If someone distributes a package in the form of a single .py file, you can wrap it in an egg by tacking an #egg=name-version suffix on the file’s URL. So, something like this:
easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foowill install the package as an egg, and this:
easy_install -zmaxd. \ -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foowill create a .egg file in the current directory.
Creating your own Package Index¶In addition to local directories and the Python Package Index, EasyInstall can find download links on most any web page whose URL is given to the -f (--find-links) option. In the simplest case, you can simply he a web page with links to eggs or Python source packages, even an automatically generated directory listing (such as the Apache web server provides).
If you are setting up an intranet site for package downloads, you may want to configure the target machines to use your download site by default, adding something like this to their configuration files:
[easy_install] find_links = http://mypackages.example.com/somedir/ http://turbogears.org/download/ http://peak.telecommunity.com/dist/As you can see, you can list multiple URLs separated by whitespace, continuing on multiple lines if necessary (as long as the subsequent lines are indented.
If you are more ambitious, you can also create an entirely custom package index or PyPI mirror. See the --index-url option under Command-Line Options, below, and also the section on 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.
Using .pypirc Credentials¶In additional to supplying credentials in the URL, easy_install will also honor credentials if present in the .pypirc file. Teams maintaining a private repository of packages may already he defined access credentials for uploading packages according to the distutils documentation. easy_install will attempt to honor those if present. Refer to the distutils documentation for Python 2.5 or later for details on the syntax.
Controlling Build Options¶EasyInstall respects standard distutils Configuration Files, so you can use them to configure build options for packages that it installs from source. For example, if you are on Windows using the MinGW compiler, you can configure the default compiler by putting something like this:
[build] compiler = mingw32into the appropriate distutils configuration file. In fact, since this is just normal distutils configuration, it will affect any builds using that config file, not just ones done by EasyInstall. For example, if you add those lines to distutils.cfg in the distutils package directory, it will be the default compiler for all packages you build. See Configuration Files below for a list of the standard configuration file locations, and links to more documentation on using distutils configuration files.
Editing and Viewing Source Packages¶Sometimes a package’s source distribution contains additional documentation, examples, configuration files, etc., that are not part of its actual code. If you want to be able to examine these files, you can use the --editable option to EasyInstall, and EasyInstall will look for a source distribution or Subversion URL for the package, then download and extract it or check it out as a subdirectory of the --build-directory you specify. If you then wish to install the package after editing or configuring it, you can do so by rerunning EasyInstall with that directory as the target.
Note that using --editable stops EasyInstall from actually building or installing the package; it just finds, obtains, and possibly unpacks it for you. This allows you to make changes to the package if necessary, and to either install it in development mode using setup.py develop (if the package uses setuptools, that is), or by running easy_install projectdir (where projectdir is the subdirectory EasyInstall created for the downloaded package.
In order to use --editable (-e for short), you must also supply a --build-directory (-b for short). The project will be placed in a subdirectory of the build directory. The subdirectory will he the same name as the project itself, but in all-lowercase. If a file or directory of that name already exists, EasyInstall will print an error message and exit.
Also, when using --editable, you cannot use URLs or filenames as arguments. You must specify project names (and optional version requirements) so that EasyInstall knows what directory name(s) to create. If you need to force EasyInstall to use a particular URL or filename, you should specify it as a --find-links item (-f for short), and then also specify the project name, e.g.:
easy_install -eb ~/projects \ -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \ ctypes==0.9.6 Dealing with Installation Conflicts¶(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that people using older versions of EasyInstall can consult it. As of version 0.6a11, installation conflicts are handled automatically without deleting the old or system-installed packages, and without ignoring the issue. Instead, eggs are automatically shifted to the front of sys.path using special code added to the easy-install.pth file. So, if you are using version 0.6a11 or better of setuptools, you do not need to worry about conflicts, and the following issues do not apply to you.)
EasyInstall installs distributions in a “managed” way, such that each distribution can be independently activated or deactivated on sys.path. However, packages that were not installed by EasyInstall are “unmanaged”, in that they usually live all in one directory and cannot be independently activated or deactivated.
As a result, if you are using EasyInstall to upgrade an existing package, or to install a package with the same name as an existing package, EasyInstall will warn you of the conflict. (This is an improvement over setup.py install, because the distutils just install new packages on top of old ones, possibly combining two unrelated packages or leing behind modules that he been deleted in the newer version of the package.)
EasyInstall will stop the installation if it detects a conflict between an existing, “unmanaged” package, and a module or package in any of the distributions you’re installing. It will display a list of all of the existing files and directories that would need to be deleted for the new package to be able to function correctly. To proceed, you must manually delete these conflicting files and directories and re-run EasyInstall.
Of course, once you’ve replaced all of your existing “unmanaged” packages with versions managed by EasyInstall, you won’t he any more conflicts to worry about!
Compressed Installation¶EasyInstall tries to install packages in zipped form, if it can. Zipping packages can improve Python’s overall import performance if you’re not using the --multi-version option, because Python processes zipfile entries on sys.path much faster than it does directories.
As of version 0.5a9, EasyInstall analyzes packages to determine whether they can be safely installed as a zipfile, and then acts on its analysis. (Previous versions would not install a package as a zipfile unless you used the --zip-ok option.)
The current analysis approach is fairly conservative; it currently looks for:
Any use of the __file__ or __path__ variables (which should be replaced with pkg_resources API calls)
Possible use of inspect functions that expect to manipulate source files (e.g. inspect.getsource())
Top-level modules that might be scripts used with python -m (Python 2.4)
If any of the above are found in the package being installed, EasyInstall will assume that the package cannot be safely run from a zipfile, and unzip it to a directory instead. You can override this analysis with the -zip-ok flag, which will tell EasyInstall to install the package as a zipfile anyway. Or, you can use the --always-unzip flag, in which case EasyInstall will always unzip, even if its analysis says the package is safe to run as a zipfile.
Normally, however, it is simplest to let EasyInstall handle the determination of whether to zip or unzip, and only specify overrides when needed to work around a problem. If you find you need to override EasyInstall’s guesses, you may want to contact the package author and the EasyInstall maintainers, so that they can make appropriate changes in future versions.
(Note: If a package uses setuptools in its setup script, the package author has the option to declare the package safe or unsafe for zipped usage via the zip_safe argument to setup(). If the package author makes such a declaration, EasyInstall believes the package’s author and does not perform its own analysis. However, your command-line option, if any, will still override the package author’s choice.)