Requirements files

When installing software, and Python packages in particular, it’s common that you get a lot of libraries installed. You just did easy_install MyPackage 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? Requirements files give you a way to create an environment: a set of packages that work together.

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 pip install MyApp and getting whatever libraries come along, you can create a requirements file something like:


If you save this in requirements.txt, then you can pip install -r requirements.txt. Regardless of what MyApp lists in, you’ll get a specific version of Framework (0.9.4) and at least the 0.2 version of Library. (You might think you could list these specific versions in MyApp’s – but if you do that you’ll have to edit MyApp if you want to try a new version of Framework, or release a new version of MyApp if you determine that Library 0.3 doesn’t work with your application.) You can also add optional libraries and support tools that MyApp doesn’t strictly require, giving people a set of recommended libraries.

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.

Requirement files are mostly flat. Maybe MyApp requires Framework, and Framework requires Library. I encourage you to still list all these in a single requirement file; it is the nature of Python programs that there are implicit bindings directly between MyApp and Library. For instance, Framework might expose one of Library’s objects, and so if Library is updated it might directly break MyApp. If that happens you can update the requirements file to force an earlier version of Library, and you can do that without having to re-release MyApp at all.

Read the requirements file format to learn about other features.

Freezing Requirements

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.

The requirements file format

The requirements file is a way to get pip to install specific packages to make up an environment. This document describes that format. To read about when you should use requirement files, see Requirements Files.

Each line of the requirements file indicates something to be installed. For example:


tells pip to install the 3.0 version of MyPackage.

You can also request extras in the requirements file:

MyPackage==3.0 [PDF]

Packages may also be installed in an “editable” form. This puts the source code into src/distname (making the name lower case) and runs python develop on the package. To indicate editable, use -e, like:

-e svn+

The #egg=MyProject part is important, because while you can install simply given the svn location, the project name is useful in other places.

You can also specify the egg name for a non-editable url. This is useful to point to HEAD locations on the local filesystem:

or relative paths:

If you need to give pip (and by association easy_install) hints about where to find a package, you can use the -f (--find-links) option, like:

$ pip -f MyPackage==3.0

Pip will then look for a link at that matches version 3.0 of MyPackage – the link should be like MyPackage-3.0.tar.gz.

And if you want to install from a tarball or zip file with a direct link, you don’t need -f option, you just need to pass the absolute url, like:

$ pip install

Version Control

Right now pip knows of the following major version control systems:


Pip supports the URL schemes svn, svn+svn, svn+http, svn+https, svn+ssh. You can also give specific revisions to an SVN URL, like:

-e svn+svn://
-e svn+

which will check out revision 2019. @{20080101} would also check out the revision from 2008-01-01. You can only check out specific revisions using -e svn+....


Pip currently supports cloning over git, git+http and git+ssh:

-e git://
-e git+
-e git+ssh://

Passing branch names, a commit hash or a tag name is also possible:

-e git://
-e git://
-e git://


The supported schemes are: hg+http, hg+https, hg+static-http and hg+ssh:

-e hg+
-e hg+
-e hg+ssh://

You can also specify a revision number, a revision hash, a tag name or a local branch name:

-e hg+
-e hg+
-e hg+
-e hg+


Pip supports Bazaar using the bzr+http, bzr+https, bzr+ssh, bzr+sftp, bzr+ftp and bzr+lp schemes:

-e bzr+
-e bzr+s
-e bzr+ssh://
-e bzr+
-e bzr+lp:MyProject#egg=MyProject

Tags or revisions can be installed like this:

-e bzr+
-e bzr+

Recursive Requirements

If you wish, you can also refer to other requirements files, like:

-r Pylons-requirements.txt

This gives you a way of abstracting out sets of requirements. This isn’t, however, very friendly with frozen requirements, as everything in Pylons-requirements.txt will show up in your frozen file.

Table Of Contents

Previous topic


Next topic


This Page