mirror of
https://github.com/pypa/pip
synced 2023-12-13 21:30:23 +01:00
241 lines
9.1 KiB
Plaintext
241 lines
9.1 KiB
Plaintext
.. _`requirements file`:
|
|
|
|
==================
|
|
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 MyApp`` 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 (0.9.4) and at least the 0.2 version of
|
|
Library. (You might think you could list these specific versions in
|
|
MyApp's ``setup.py`` -- 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 <http://pip.openplans.org/requirement-format.html>`_ 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 <./#requirements-files>`_.
|
|
|
|
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.
|
|
|
|
You can also specify the egg name for a non-editable url. This is useful to
|
|
point to HEAD locations on the local filesystem:
|
|
|
|
file:///path/to/your/lib/project#egg=MyProject
|
|
|
|
or relative paths:
|
|
|
|
file:../../lib/project#egg=MyProject
|
|
|
|
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 http://someserver.org/index-of-packages MyPackage==3.0
|
|
|
|
Pip will then look for a link at http://someserver.org/index-of-packages
|
|
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 http://someserver.org/packages/MyPackage-3.0.tar.gz
|
|
|
|
|
|
Version Control
|
|
---------------
|
|
|
|
Right now pip knows of the following major version control systems:
|
|
|
|
Subversion
|
|
~~~~~~~~~~
|
|
|
|
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://svn.myproject.org/svn/MyProject#egg=MyProject
|
|
-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``, ``hg+https``,
|
|
``hg+static-http`` and ``hg+ssh``::
|
|
|
|
-e hg+http://hg.myproject.org/MyProject/#egg=MyProject
|
|
-e hg+https://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``,
|
|
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` 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
|
|
-e bzr+ftp://user@myproject.org/MyProject/trunk/#egg=MyProject
|
|
-e bzr+lp:MyProject#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
|
|
|
|
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
|
|
<./#freezing-requirements>`_, as everything in
|
|
``Pylons-requirements.txt`` will show up in your frozen file.
|
|
|
|
Indexes, find-links
|
|
-------------------
|
|
|
|
You can also provide values for the ``--index-url`` and ``--find-links``
|
|
options in your requirement files, like::
|
|
|
|
--index-url http://example.com/private-pypi/
|
|
|
|
Note that using ``--index-url`` removes the use of `PyPI
|
|
<http://pypi.python.org>`_, while using ``--extra-index-url`` will add
|
|
additional indexes.
|
|
|
|
``--find-links`` is more ad-hoc; instead of a complete "index", you
|
|
only need an HTML page of links to available packages. Simply by
|
|
putting all your private packages in a directory and using the Apache
|
|
auto-index, you can publish your packages so pip can find them.
|
|
``--find-links`` is always additive; pip looks at everything it can
|
|
find. Use it like::
|
|
|
|
--find-links http://example.com/private-packages/
|
|
|
|
Note that all these options must be on a line of their own.
|