ez_setup distribution guide

Using setuptools… Without bundling it!

Warning

ez_setup is deprecated in favor of PIP with PEP-518 support.

Your users might not have setuptools installed on their machines, or even if they do, it might not be the right version. Fixing this is easy; just download ez_setup.py, and put it in the same directory as your setup.py script. (Be sure to add it to your revision control system, too.) Then add these two lines to the very top of your setup script, before the script imports anything from setuptools:

import ez_setup
ez_setup.use_setuptools()

That’s it. The ez_setup module will automatically download a matching version of setuptools from PyPI, if it isn’t present on the target system. Whenever you install an updated version of setuptools, you should also update your projects’ ez_setup.py files, so that a matching version gets installed on the target machine(s).

(By the way, if you need to distribute a specific version of setuptools, you can specify the exact version and base download URL as parameters to the use_setuptools() function. See the function’s docstring for details.)

What Your Users Should Know

In general, a setuptools-based project looks just like any distutils-based project – as long as your users have an internet connection and are installing to site-packages, that is. But for some users, these conditions don’t apply, and they may become frustrated if this is their first encounter with a setuptools-based project. To keep these users happy, you should review the following topics in your project’s installation instructions, if they are relevant to your project and your target audience isn’t already familiar with setuptools and easy_install.

Network Access

If your project is using ez_setup, you should inform users of the need to either have network access, or to preinstall the correct version of setuptools using the EasyInstall installation instructions. Those instructions also have tips for dealing with firewalls as well as how to manually download and install setuptools.

Custom Installation Locations

You should inform your users that if they are installing your project to somewhere other than the main site-packages directory, they should first install setuptools using the instructions for Custom Installation Locations, before installing your project.

Your Project’s Dependencies

If your project depends on other projects that may need to be downloaded from PyPI or elsewhere, you should list them in your installation instructions, or tell users how to find out what they are. While most users will not need this information, any users who don’t have unrestricted internet access may have to find, download, and install the other projects manually. (Note, however, that they must still install those projects using easy_install, or your project will not know they are installed, and your setup script will try to download them again.)

If you want to be especially friendly to users with limited network access, you may wish to build eggs for your project and its dependencies, making them all available for download from your site, or at least create a page with links to all of the needed eggs. In this way, users with limited network access can manually download all the eggs to a single directory, then use the -f option of easy_install to specify the directory to find eggs in. Users who have full network access can just use -f with the URL of your download page, and easy_install will find all the needed eggs using your links directly. This is also useful when your target audience isn’t able to compile packages (e.g. most Windows users) and your package or some of its dependencies include C code.

Revision Control System Users and Co-Developers

Users and co-developers who are tracking your in-development code using a revision control system should probably read this manual’s sections regarding such development. Alternately, you may wish to create a quick-reference guide containing the tips from this manual that apply to your particular situation. For example, if you recommend that people use setup.py develop when tracking your in-development code, you should let them know that this needs to be run after every update or commit.

Similarly, if you remove modules or data files from your project, you should remind them to run setup.py clean --all and delete any obsolete .pyc or .pyo. (This tip applies to the distutils in general, not just setuptools, but not everybody knows about them; be kind to your users by spelling out your project’s best practices rather than leaving them guessing.)

Creating System Packages

Some users want to manage all Python packages using a single package manager, and sometimes that package manager isn’t easy_install! Setuptools currently supports bdist_rpm, bdist_wininst, and bdist_dumb formats for system packaging. If a user has a locally- installed “bdist” packaging tool that internally uses the distutils install command, it should be able to work with setuptools. Some examples of “bdist” formats that this should work with include the bdist_nsi and bdist_msi formats for Windows.

However, packaging tools that build binary distributions by running setup.py install on the command line or as a subprocess will require modification to work with setuptools. They should use the --single-version-externally-managed option to the install command, combined with the standard --root or --record options. See the install command documentation below for more details. The bdist_deb command is an example of a command that currently requires this kind of patching to work with setuptools.

Please note that building system packages may require you to install some system software, for example bdist_rpm requires the rpmbuild command to be installed.

If you or your users have a problem building a usable system package for your project, please report the problem via the mailing list so that either the “bdist” tool in question or setuptools can be modified to resolve the issue.

Your users might not have setuptools installed on their machines, or even if they do, it might not be the right version. Fixing this is easy; just download ez_setup.py, and put it in the same directory as your setup.py script. (Be sure to add it to your revision control system, too.) Then add these two lines to the very top of your setup script, before the script imports anything from setuptools:

import ez_setup
ez_setup.use_setuptools()

That’s it. The ez_setup module will automatically download a matching version of setuptools from PyPI, if it isn’t present on the target system. Whenever you install an updated version of setuptools, you should also update your projects’ ez_setup.py files, so that a matching version gets installed on the target machine(s).

(By the way, if you need to distribute a specific version of setuptools, you can specify the exact version and base download URL as parameters to the use_setuptools() function. See the function’s docstring for details.)

install - Run easy_install or old-style installation

The setuptools install command is basically a shortcut to run the easy_install command on the current project. However, for convenience in creating “system packages” of setuptools-based projects, you can also use this option:

--single-version-externally-managed

This boolean option tells the install command to perform an “old style” installation, with the addition of an .egg-info directory so that the installed project will still have its metadata available and operate normally. If you use this option, you must also specify the --root or --record options (or both), because otherwise you will have no way to identify and remove the installed files.

This option is automatically in effect when install is invoked by another distutils command, so that commands like bdist_wininst and bdist_rpm will create system packages of eggs. It is also automatically in effect if you specify the --root option.

install_egg_info - Install an .egg-info directory in site-packages

Setuptools runs this command as part of install operations that use the --single-version-externally-managed options. You should not invoke it directly; it is documented here for completeness and so that distutils extensions such as system package builders can make use of it. This command has only one option:

--install-dir=DIR, -d DIR

The parent directory where the .egg-info directory will be placed. Defaults to the same as the --install-dir option specified for the install_lib command, which is usually the system site-packages directory.

This command assumes that the egg_info command has been given valid options via the command line or setup.cfg, as it will invoke the egg_info command and use its options to locate the project’s source .egg-info directory.