7
.. _`Requirements File Format`:
9
Requirements File Format
10
========================
12
Each line of the requirements file indicates something to be installed,
13
and like arguments to :ref:`pip install`, the following forms are supported::
15
<requirement specifier>
17
[-e] <local project path>
18
[-e] <vcs project url>
20
See the :ref:`pip install Examples<pip install Examples>` for examples of all these forms.
22
A line beginning with ``#`` is treated as a comment and ignored.
24
Additionally, the following :ref:`Package Index Options <Package Index Options>` are supported
26
* :ref:`-i, --index-url <--index-url>`
27
* :ref:`--extra-index-url <--extra-index-url>`
28
* :ref:`--no-index <--no-index>`
29
* :ref:`-f, --find-links <--find-links>`
31
For example, to specify :ref:`--no-index <--no-index>` and 2 :ref:`--find-links <--find-links>` locations:
36
--find-links /my/local/archives
37
--find-links http://some.archives.com/archives
40
Lastly, if you wish, you can refer to other requirements files, like this::
42
-r more_requirements.txt
44
.. _`Requirement Specifiers`:
46
Requirement Specifiers
47
======================
49
pip supports installing from "requirement specifiers" as implemented in
50
`pkg_resources Requirements <http://packages.python.org/setuptools/pkg_resources.html#requirement-objects>`_
58
'PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1'
59
SomethingWhoseVersionIDontCareAbout
63
Use single or double quotes around specifiers to avoid ``>`` and ``<`` being interpreted as shell redirects. e.g. ``pip install 'FooProject>=1.2'``.
65
.. _`Pre Release Versions`:
70
Starting with v1.4, pip will only install stable versions as specified by `PEP426`_ by default. If
71
a version cannot be parsed as a compliant `PEP426`_ version then it is assumed
74
If a Requirement specifier includes a pre-release or development version (e.g. ``>=0.0.dev0``) then
75
pip will allow pre-release and development versions for that requirement. This does not include
78
The ``pip install`` command also supports a :ref:`--pre <install_--pre>` flag that will enable
79
installing pre-releases and development releases.
82
.. _PEP426: http://www.python.org/dev/peps/pep-0426
84
.. _`Externally Hosted Files`:
86
Externally Hosted Files
87
=======================
89
Starting with v1.4, pip will warn about installing any file that does not come
90
from the primary index. In future versions pip will default to ignoring these
91
files unless asked to consider them.
93
The ``pip install`` command supports a
94
:ref:`--allow-external PROJECT <--allow-external>` option that will enable
95
installing links that are linked directly from the simple index but to an
96
external host that also have a supported hash fragment. Externally hosted
97
files for all projects may be enabled using the
98
:ref:`--allow-all-external <--allow-all-external>` flag to the ``pip install``
101
The ``pip install`` command also supports a
102
:ref:`--allow-insecure PROJECT <--allow-insecure>` option that will enable
103
installing insecurely linked files. These are either directly linked (as above)
104
files without a hash, or files that are linked from either the home page or the
105
download url of a package.
107
In order to get the future behavior in v1.4 the ``pip install`` command
108
supports a :ref:`--no-allow-external <--no-allow-external>` and
109
:ref:`--no-allow-insecure <--no-allow-external>` flags.
116
pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects the type of VCS using url prefixes: "git+", "hg+", "bzr+", "svn+".
118
pip requires a working VCS command on your path: git, hg, svn, or bzr.
120
VCS projects can be installed in :ref:`editable mode <editable-installs>` (using the :ref:`--editable <install_--editable>` option) or not.
122
* For editable installs, the clone location by default is "<venv path>/src/SomeProject" in virtual environments, and "<cwd>/src/SomeProject" for global installs.
123
The :ref:`--src <install_--src>` option can be used to modify this location.
124
* For non-editable installs, the project is built locally in a temp dir and then installed normally.
126
The url suffix "egg=<project name>" is used by pip in it's dependency logic to identify the project prior to pip downloading and analyzing the metadata.
131
pip currently supports cloning over ``git``, ``git+https`` and ``git+ssh``:
133
Here are the supported forms::
135
[-e] git+git://git.myproject.org/MyProject#egg=MyProject
136
[-e] git+https://git.myproject.org/MyProject#egg=MyProject
137
[-e] git+ssh://git.myproject.org/MyProject#egg=MyProject
138
-e git+git@git.myproject.org:MyProject#egg=MyProject
140
Passing branch names, a commit hash or a tag name is possible like so::
142
[-e] git://git.myproject.org/MyProject.git@master#egg=MyProject
143
[-e] git://git.myproject.org/MyProject.git@v1.0#egg=MyProject
144
[-e] git://git.myproject.org/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject
149
The supported schemes are: ``hg+http``, ``hg+https``,
150
``hg+static-http`` and ``hg+ssh``.
152
Here are the supported forms::
154
[-e] hg+http://hg.myproject.org/MyProject#egg=MyProject
155
[-e] hg+https://hg.myproject.org/MyProject#egg=MyProject
156
[-e] hg+ssh://hg.myproject.org/MyProject#egg=MyProject
158
You can also specify a revision number, a revision hash, a tag name or a local
159
branch name like so::
161
[-e] hg+http://hg.myproject.org/MyProject@da39a3ee5e6b#egg=MyProject
162
[-e] hg+http://hg.myproject.org/MyProject@2019#egg=MyProject
163
[-e] hg+http://hg.myproject.org/MyProject@v1.0#egg=MyProject
164
[-e] hg+http://hg.myproject.org/MyProject@special_feature#egg=MyProject
169
pip supports the URL schemes ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``, ``svn+ssh``.
171
You can also give specific revisions to an SVN URL, like so::
173
[-e] svn+svn://svn.myproject.org/svn/MyProject#egg=MyProject
174
[-e] svn+http://svn.myproject.org/svn/MyProject/trunk@2019#egg=MyProject
176
which will check out revision 2019. ``@{20080101}`` would also check
177
out the revision from 2008-01-01. You can only check out specific
178
revisions using ``-e svn+...``.
183
pip supports Bazaar using the ``bzr+http``, ``bzr+https``, ``bzr+ssh``,
184
``bzr+sftp``, ``bzr+ftp`` and ``bzr+lp`` schemes.
186
Here are the supported forms::
188
[-e] bzr+http://bzr.myproject.org/MyProject/trunk#egg=MyProject
189
[-e] bzr+sftp://user@myproject.org/MyProject/trunk#egg=MyProject
190
[-e] bzr+ssh://user@myproject.org/MyProject/trunk#egg=MyProject
191
[-e] bzr+ftp://user@myproject.org/MyProject/trunk#egg=MyProject
192
[-e] bzr+lp:MyProject#egg=MyProject
194
Tags or revisions can be installed like so::
196
[-e] bzr+https://bzr.myproject.org/MyProject/trunk@2019#egg=MyProject
197
[-e] bzr+http://bzr.myproject.org/MyProject/trunk@v1.0#egg=MyProject
203
pip searches for packages on `PyPI <http://pypi.python.org>`_ using the
204
`http simple interface <http://pypi.python.org/simple>`_,
205
which is documented `here <http://packages.python.org/setuptools/easy_install.html#package-index-api>`_
206
and `there <http://www.python.org/dev/peps/pep-0301/>`_
208
pip offers a set of :ref:`Package Index Options <Package Index Options>` for modifying how packages are found.
210
See the :ref:`pip install Examples<pip install Examples>`.
213
.. _`SSL Certificate Verification`:
215
SSL Certificate Verification
216
============================
218
Starting with v1.3, pip provides SSL certificate verification over https, for the purpose
219
of providing secure, certified downloads from PyPI.
225
PyPI provides md5 hashes in the hash fragment of package download urls.
227
pip supports checking this, as well as any of the
228
guaranteed hashlib algorithms (sha1, sha224, sha384, sha256, sha512, md5).
230
The hash fragment is case sensitive (i.e. sha1 not SHA1).
232
This check is only intended to provide basic download corruption protection.
233
It is not intended to provide security against tampering. For that,
234
see :ref:`SSL Certificate Verification`
240
pip offers a :ref:`--download-cache <install_--download-cache>` option for installs to prevent redundant downloads of archives from PyPI.
242
The point of this cache is *not* to circumvent the index crawling process, but to *just* prevent redundant downloads.
244
Items are stored in this cache based on the url the archive was found at, not simply the archive name.
246
If you want a fast/local install solution that circumvents crawling PyPI, see the :ref:`Fast & Local Installs` Cookbook entry.
248
Like all options, :ref:`--download-cache <install_--download-cache>`, can also be set as an environment variable, or placed into the pip config file.
249
See the :ref:`Configuration` section.
252
.. _`editable-installs`:
257
"Editable" installs are fundamentally `"setuptools develop mode" <http://packages.python.org/setuptools/setuptools.html#development-mode>`_ installs.
259
You can install local projects or VCS projects in "editable" mode::
261
$ pip install -e path/to/SomeProject
262
$ pip install -e git+http://repo/my_project.git#egg=SomeProject
264
For local projects, the "SomeProject.egg-info" directory is created relative to the project path.
265
This is one advantage over just using ``setup.py develop``, which creates the "egg-info" directly relative the current working directory.
268
setuptools & pkg_resources
269
==========================
271
Internally, pip uses the `setuptools` package, and the `pkg_resources` module, which are available from the project, `Setuptools`_.
273
Here are some examples of how pip uses `setuptools` and `pkg_resources`:
275
* The core of pip's install process uses the `setuptools`'s "install" command.
276
* Editable ("-e") installs use the `setuptools`'s "develop" command.
277
* pip uses `pkg_resources` for version parsing, for detecting version conflicts, and to determine what projects are installed,
280
.. _Setuptools: http://pypi.python.org/pypi/setuptools/
added
removed
docs/logic.rst
