Project
Requirements files serve as a list of items to be installed by pip, whenusingpip install. Files that use this format are often called“pip requirements.txt files”, sincerequirements.txt is usually whatthese files are named (although, that is not a requirement).
Note
The requirements file format is closely tied to a number of internal details ofpip (e.g., pip’s command line options). The basic format is relatively stableand portable but the full syntax, as described here, is only intended forconsumption by pip, and other tools should take that into account before usingit for their own purposes.
# This is a comment, to show how #-prefixed lines are ignored.# It is possible to specify requirements as plain names.pytestpytest-covbeautifulsoup4# The syntax supported here is the same as that of requirement specifiers.docopt==0.6.1requests[security]>=2.8.1,==2.8.*;python_version<"2.7"urllib3@https://github.com/urllib3/urllib3/archive/refs/tags/1.26.8.zip# It is possible to refer to other requirement files or constraints files.-rother-requirements.txt-cconstraints.txt# It is possible to refer to specific local distribution paths../downloads/numpy-1.9.2-cp34-none-win32.whl# It is possible to refer to URLs.http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl
Each line of the requirements file indicates something to be installed,or arguments topip install. The following forms are supported:
[[--option]...]
<requirementspecifier>
<archiveurl/path>
[-e]<localprojectpath>
[-e]<vcsprojecturl>
For details on requirement specifiers, seeRequirement Specifiers. Forexamples of all these forms, seeExamples.
The default encoding for requirement files isUTF-8 unless a differentencoding is specified using aPEP 263 style comment (e.g.#-*-coding:<encodingname>-*-).
A line ending in an unescaped\ is treated as a line continuationand the newline following it is effectively ignored.
A line that begins with# is treated as a comment and ignored. Whitespacefollowed by a# causes the# and the remainder of the line to betreated as a comment.
Comments are strippedafter line continuations are processed.
Requirements files only supports certain pip install options, which are listedbelow.
The following options have an effect on theentirepipinstall run, andmust be specified on their individual lines.
Example
To specify--pre,--no-indexand two--find-links locations:
--pre--no-index--find-links/my/local/archives--find-linkshttp://some.archives.com/archives
Added in version 7.0.
The options which can be applied to individual requirements are:
If you wish, you can refer to other requirements files, like this:
-rmore_requirements.txt
You can also refer toconstraints files, like this:
-csome_constraints.txt
Added in version 10.0.
pip supports the use of environment variables inside therequirements file.
You have to use the POSIX format for variable names including brackets aroundthe uppercase name as shown in this example:${API_TOKEN}. pip will attemptto find the corresponding environment variable defined on the host system atruntime.
Note
There is no support for other variable expansion syntaxes such as$VARIABLEand%VARIABLE%.
You can now store sensitive data (tokens, keys, etc.) in environment variablesand only specify the variable name for your requirements, letting pip lookupthe value at runtime. This approach aligns with the commonly used12-factor configuration pattern.
Danger
This disables the use of wheels (cached or otherwise). This could mean that builds will be slower, less deterministic, less reliable and may not behave correctly upon installation.
This mechanism is only preserved for backwards compatibility and should be considered deprecated. A future release of pip may drop these options.
The--global-option option is used to pass options tosetup.py.
Attention
These options are highly coupled with how pip invokes setuptools using thesetup.py (legacy) build system interface. It is not compatible with newerpyproject.toml build system interface.
This is will not work with other build-backends or newer setup.cfg-only projects.
If you have a declaration like:
FooProject >= 1.2 --global-option="--no-user-cfg"
The above translates roughly into running FooProject’ssetup.py script as:
python setup.py --no-user-cfg install
Note that the only way of giving more than one option tosetup.py is through multiple--global-option options.