When installing software, and Python packages in particular, it’s common that
you get a lot of libraries installed. You just did easy_installMyPackage
and you get a dozen packages. Each of these packages has its own version.

Maybe you ran that installation and it works. Great! Will it keep working?
Did you have to provide special options to get it to find everything? Did you
have to install a bunch of other optional pieces? Most of all, will you be able
to do it again?

If you’ve ever tried to setup an application on a new system, or with slightly
updated pieces, and had it fail, pip requirements are for you. If you
haven’t had this problem then you will eventually, so pip requirements are
for you too – requirements make explicit, repeatable installation of packages.

So what are requirements files? They are very simple: lists of packages to
install. Instead of running something like pipMyApp and getting
whatever libraries come along, you can create a requirements file something like:

MyApp
Framework==0.9.4
Library>=0.2

Then, regardless of what MyApp lists in setup.py, you’ll get a specific
version of Framework and at least the 0.2 version of Library. (You might think
you could list these specific versions in setup.py – try it and you’ll
quickly see why that doesn’t work.) You can add optional libraries and support
tools that MyApp doesn’t strictly require.

You can also include “editable” packages – packages that are checked out from
Subversion, Git, Mercurial and Bazaar. These are just like using the -e
option to pip. They look like:

-e svn+http://myrepo/svn/MyApp#egg=MyApp

You have to start the URL with svn+ (git+, hg+ or bzr+), and
you have to include #egg=Package so pip knows what to expect at that URL.
You can also include @rev in the URL, e.g., @275 to check out
revision 275.

So you have a working set of packages, and you want to be able to install them
elsewhere. Requirements files let you install exact versions, but it won’t
tell you what all the exact versions are.

To create a new requirements file from a known working environment, use:

$ pip freeze > stable-req.txt

This will write a listing of all installed libraries to stable-req.txt
with exact versions for every library. You may want to edit the file down after
generating (e.g., to eliminate unnecessary libraries), but it’ll give you a
stable starting point for constructing your requirements file.

You can also give it an existing requirements file, and it will use that as a
sort of template for the new file. So if you do:

$ pip freeze -r devel-req.txt > stable-req.txt

it will keep the packages listed in devel-req.txt in order and preserve
comments.

Another way to distribute a set of libraries is a bundle format (specific to
pip). This format is not stable at this time (there simply hasn’t been
any feedback, nor a great deal of thought). A bundle file contains all the
source for your package, and you can have pip install them all together.
Once you have the bundle file further network access won’t be necessary. To
build a bundle file, do:

$ pip bundle MyApp.pybundle MyApp

(Using a requirements file would be wise.) Then someone else can get the
file MyApp.pybundle and run:

$ pip install MyApp.pybundle

This is not a binary format. This only packages source. If you have binary
packages, then the person who installs the files will have to have a compiler,
any necessary headers installed, etc. Binary packages are hard, this is
relatively easy.

pip is most nutritious when used with virtualenv. One of the reasons pip
doesn’t install “multi-version” eggs is that virtualenv removes much of the need
for it.

pip does not have to be installed to use it, you can run pythonpath/to/pip.py and it will work. This is intended to avoid the
bootstrapping problem of installation. You can also run pip inside
any virtualenv environment, like: