The requirements file format
============================

The requirements file is what pip uses to install packages.
This document describes that format.

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

    MyPackage==3.0

tells pip to install the 3.0 version of MyPackage.  

You can also install a package in an "editable" form.  This puts the
source code into ``src/distname`` (making the name lower case) and
runs ``python setup.py develop`` on the package.  To indicate
editable, use ``-e``, like::

    -e svn+http://svn.myproject.org/svn/MyProject/trunk#egg=MyProject

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

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::

    -f http://someserver.org/MyPackage-3.0.tar.gz

If the package is named like ``PackageName-Version.tar.gz`` (or a zip)
then you don't need ``#egg=...``.  Note that you cannot provide
multiple ``-f`` arguments to easy_install, but you can in a
requirements file (they all get concatenated into a single ``-f`` for
easy_install).

Version Control
---------------

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

Subversion
~~~~~~~~~~

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

    -e svn+http://svn.myproject.org/svn/MyProject/trunk@2019#egg=MyProject

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+...``.

Git
~~~

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

    -e git://git.myproject.org/MyProject.git#egg=MyProject
    -e git+http://git.myproject.org/MyProject/#egg=MyProject
    -e git+ssh://git@myproject.org/MyProject/#egg=MyProject

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

    -e git://git.myproject.org/MyProject.git@master#egg=MyProject
    -e git://git.myproject.org/MyProject.git@v1.0#egg=MyProject
    -e git://git.myproject.org/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject

Mercurial
~~~~~~~~~

The supported schemes are: ``hg+http`` and ``hg+ssh``::

    -e hg+http://hg.myproject.org/MyProject/#egg=MyProject
    -e hg+ssh://hg@myproject.org/MyProject/#egg=MyProject

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

    -e hg+http://hg.myproject.org/MyProject/@da39a3ee5e6b#egg=MyProject
    -e hg+http://hg.myproject.org/MyProject/@2019#egg=MyProject
    -e hg+http://hg.myproject.org/MyProject/@v1.0#egg=MyProject
    -e hg+http://hg.myproject.org/MyProject/@special_feature#egg=MyProject

Bazaar
~~~~~~

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

    -e bzr+http://bzr.myproject.org/MyProject/trunk/#egg=MyProject
    -e bzr+sftp://user@myproject.org/MyProject/trunk/#egg=MyProject
    -e bzr+ssh://user@myproject.org/MyProject/trunk/#egg=MyProject

Tags or revisions can be installed like this::

    -e bzr+https://bzr.myproject.org/MyProject/trunk/@2019#egg=MyProject
    -e bzr+http://bzr.myproject.org/MyProject/trunk/@v1.0#egg=MyProject