Introduction

pip is a replacement foreasy_install. It uses mostly thesame techniques for finding packages, so packages that were madeeasy_installable should be pipable as well.

pip is meant to improve on easy_install. Some of the improvements:

• All packages are downloaded before installation. Partially-completedinstallation doesn’t occur as a result.

• Care is taken to present useful output on the console.

• The reasons for actions are kept track of. For instance, if a package isbeing installed, pip keeps track of why that package was required.

• Error messages should be useful.

• The code is relatively concise and cohesive, making it easier to useprogrammatically.

• Packages don’t have to be installed as egg archives, they can be installedflat (while keeping the egg metadata).

• Maybe features like native support for other version control systems, oruninstallation, will get added. (They might get added to easy_install, but Ithink the chance for pip is higher.)

Also, pip will eventually be merged directly with poacheggs, making itsimple to define fixed sets of requirements and reliably reproduce a set ofpackages.

pip is complementary withvirtualenv, and it is encouraged that you usevirtualenv to isolate your installation.

Community

The homepage for pip is temporarily locatedon PyPI – a more proper homepagewill follow. Bugs can go on thepoacheggs Trac instance (probably that will changetoo). Discussion should happen on thevirtualenv email group.

Differences From easy_install

pip cannot install some packages. Specifically:

• It cannot install from eggs. It only installs from source. (Maybe this willbe changed sometime, but it’s low priority.)

• It doesn’t understand Setuptools extras (likepackage[test]). This shouldbe added eventually.

• It is incompatible with some packages that customize distutils or setuptoolsin theirsetup.py files.

• Maybe it doesn’t work on Windows. At least, the author doesn’t test onWindows often.

• It also has some extra features. Extra features the author thinks are great.

Requirements Files

When installing software, and Python packages in particular, it’s common thatyou get a lot of libraries installed. You just dideasy_install MyPackageand 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 youhave to install a bunch of other optional pieces? Most of all, will you be ableto do it again?

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

So what are requirements files? They are very simple: lists of packages toinstall. Instead of running something likepip MyApp and gettingwhatever libraries come along, you can create a requirements file something like:

MyAppFramework==0.9.4Library>=0.2

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

You can also include “editable” packages – packages that are checked out fromsubversion (in the future other VCS will be supported). These are just likeusing the-e option to pip. They look like:

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

You have to start the URL withsvn+ (eventually you’ll be able to usehg+ etc), and you have to include#egg=Package so pip knows whatto expect at that URL. You can also include@rev in the URL, e.g.,@275to check out revision 275.

Freezing Requirements

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

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

$ pip freeze -o stable-req.txt

This will write a listing ofall installed libraries tostable-req.txtwith exact versions for every library. You may want to edit the file down aftergenerating (e.g., to eliminate unnecessary libraries), but it’ll give you astable starting point for constructing your requirements file.

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

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

it will keep the packages listed indevel-req.txt in order and preservecomments.

Bundles

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

$ pip install bundle=MyApp.pybundle MyApp

(Using arequirements file would be wise.) Then someone else can get thefileMyApp.pybundle and run:

$ pip install MyApp.pybundle

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

Using pip With virtualenv

pip is most nutritious when used withvirtualenv. One of the reasons pipdoesn’t install “multi-version” eggs is that virtualenv removes much of the needfor it.

pip does not have to be installed to use it, you can runpython pip and it will work. This is intended to avoid the bootstrappingproblem of installation. You can also run pip inside any virtualenvenvironment, like:

$ virtualenv new-env/... creates new-env/ ...$ pip install -E new-env/ MyPackage

This is exactly equivalent to:

$ ./new-env/bin/python pip install MyPackage

Except, if you havevirtualenv installed and the pathnew-env/doesn’t exist, then a new virtualenv will be created.