|
| 1 | +# Requirements File Format |
| 2 | + |
| 3 | +Requirements files serve as a list of items to be installed by pip, when |
| 4 | +using {ref}`pip install`. Files that use this format are often called |
| 5 | +"pip requirements.txt files", since `requirements.txt` is usually what |
| 6 | +these files are named (although, that is not a requirement). |
| 7 | + |
| 8 | +```{note} |
| 9 | +The requirements file format is closely tied to a number of internal details of |
| 10 | +pip (e.g., pip's command line options). The basic format is relatively stable |
| 11 | +and portable but the full syntax, as described here, is only intended for |
| 12 | +consumption by pip, and other tools should take that into account before using |
| 13 | +it for their own purposes. |
| 14 | +``` |
| 15 | + |
| 16 | +## Structure |
| 17 | + |
| 18 | +Each line of the requirements file indicates something to be installed, |
| 19 | +or arguments to {ref}`pip install`. The following forms are supported: |
| 20 | + |
| 21 | +- `[[--option]...]` |
| 22 | +- `<requirement specifier> [; markers] [[--option]...]` |
| 23 | +- `<archive url/path>` |
| 24 | +- `[-e] <local project path>` |
| 25 | +- `[-e] <vcs project url>` |
| 26 | + |
| 27 | +For details on requirement specifiers, see {ref}`Requirement Specifiers`. For |
| 28 | +examples of all these forms, see {ref}`pip install Examples`. |
| 29 | + |
| 30 | +### Encoding |
| 31 | + |
| 32 | +Requirements files are `utf-8` encoding by default and also support |
| 33 | +{pep}`263` style comments to change the encoding (i.e. |
| 34 | +`# -*- coding: <encoding name> -*-`). |
| 35 | + |
| 36 | +### Line continuations |
| 37 | + |
| 38 | +A line ending in an unescaped `\` is treated as a line continuation |
| 39 | +and the newline following it is effectively ignored. |
| 40 | + |
| 41 | +### Comments |
| 42 | + |
| 43 | +A line that begins with `#` is treated as a comment and ignored. Whitespace |
| 44 | +followed by a `#` causes the `#` and the remainder of the line to be |
| 45 | +treated as a comment. |
| 46 | + |
| 47 | +Comments are stripped _after_ line continuations are processed. |
| 48 | + |
| 49 | +## Supported options |
| 50 | + |
| 51 | +Requirements files only supports certain pip install options, which are listed |
| 52 | +below. |
| 53 | + |
| 54 | +### Global options |
| 55 | + |
| 56 | +The following options have an effect on the _entire_ `pip install` run, and |
| 57 | +must be specified on their individual lines. |
| 58 | + |
| 59 | +```{eval-rst} |
| 60 | +.. pip-requirements-file-options-ref-list:: |
| 61 | +``` |
| 62 | + |
| 63 | +````{admonition} Example |
| 64 | +To specify {ref}`--pre <install_--pre>`, {ref}`--no-index <install_--no-index>` |
| 65 | +and two {ref}`--find-links <install_--find-links>` locations: |
| 66 | +
|
| 67 | +``` |
| 68 | +--pre |
| 69 | +--no-index |
| 70 | +--find-links /my/local/archives |
| 71 | +--find-links http://some.archives.com/archives |
| 72 | +``` |
| 73 | +```` |
| 74 | + |
| 75 | +### Per-requirement options |
| 76 | + |
| 77 | +The options which can be applied to individual requirements are: |
| 78 | + |
| 79 | +- {ref}`--install-option <install_--install-option>` |
| 80 | +- {ref}`--global-option <install_--global-option>` |
| 81 | +- `--hash` (for {ref}`Hash-Checking mode`) |
| 82 | + |
| 83 | +If you wish, you can refer to other requirements files, like this: |
| 84 | + |
| 85 | +``` |
| 86 | +-r more_requirements.txt |
| 87 | +``` |
| 88 | + |
| 89 | +You can also refer to {ref}`constraints files <Constraints Files>`, like this: |
| 90 | + |
| 91 | +``` |
| 92 | +-c some_constraints.txt |
| 93 | +``` |
| 94 | + |
| 95 | +## Using environment variables |
| 96 | + |
| 97 | +```{versionadded} 10.0 |
| 98 | +
|
| 99 | +``` |
| 100 | + |
| 101 | +pip supports the use of environment variables inside the |
| 102 | +requirements file. |
| 103 | + |
| 104 | +You have to use the POSIX format for variable names including brackets around |
| 105 | +the uppercase name as shown in this example: `${API_TOKEN}`. pip will attempt |
| 106 | +to find the corresponding environment variable defined on the host system at |
| 107 | +runtime. |
| 108 | + |
| 109 | +```{note} |
| 110 | +There is no support for other variable expansion syntaxes such as `$VARIABLE` |
| 111 | +and `%VARIABLE%`. |
| 112 | +``` |
| 113 | + |
| 114 | +You can now store sensitive data (tokens, keys, etc.) in environment variables |
| 115 | +and only specify the variable name for your requirements, letting pip lookup |
| 116 | +the value at runtime. This approach aligns with the commonly used |
| 117 | +[12-factor configuration pattern](https://12factor.net/config). |
| 118 | + |
| 119 | +## Example |
| 120 | + |
| 121 | +``` |
| 122 | +###### Requirements without Version Specifiers ###### |
| 123 | +pytest |
| 124 | +pytest-cov |
| 125 | +beautifulsoup4 |
| 126 | +
|
| 127 | +###### Requirements with Version Specifiers ###### |
| 128 | +# See https://www.python.org/dev/peps/pep-0440/#version-specifiers |
| 129 | +docopt == 0.6.1 # Version Matching. Must be version 0.6.1 |
| 130 | +keyring >= 4.1.1 # Minimum version 4.1.1 |
| 131 | +coverage != 3.5 # Version Exclusion. Anything except version 3.5 |
| 132 | +Mopidy-Dirble ~= 1.1 # Compatible release. Same as >= 1.1, == 1.* |
| 133 | +
|
| 134 | +###### Refer to other requirements files ###### |
| 135 | +-r other-requirements.txt |
| 136 | +
|
| 137 | +###### A particular file ###### |
| 138 | +./downloads/numpy-1.9.2-cp34-none-win32.whl |
| 139 | +http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl |
| 140 | +
|
| 141 | +###### Additional Requirements without Version Specifiers ###### |
| 142 | +# Same as 1st section, just here to show that you can put things in any order. |
| 143 | +rejected |
| 144 | +green |
| 145 | +``` |
0 commit comments