Skip to content

Commit ece6a2c

Browse files
pradyunsgpradyunsg
authored
Merge pull request #10056 from pradyunsg/topic/configuration
2 parents 498d800 + 0ab159a commit ece6a2c

File tree

4 files changed

+236
-221
lines changed

4 files changed

+236
-221
lines changed

‎docs/html/conf.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@
5252
print("pip version:", version)
5353
print("pip release:", release)
5454

55+
# -- Options for myst-parser ----------------------------------------------------------
56+
57+
myst_enable_extensions = ["deflist"]
58+
5559
# -- Options for smartquotes ----------------------------------------------------------
5660

5761
# Disable the conversion of dashes so that long options like "--find-links" won't

‎docs/html/topics/configuration.md

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Configuration
2+
3+
pip allows a user to change its behaviour via 3 mechanisms:
4+
5+
- command line options
6+
- environment variables
7+
- configuration files
8+
9+
This page explains how the configuration files and environment variables work,
10+
and how they are related to pip's various command line options.
11+
12+
## Configuration Files
13+
14+
Configuration files can change the default values for command line option.
15+
They are written using a standard INI style configuration files.
16+
17+
pip has 3 "levels" of configuration files:
18+
19+
- `global`: system-wide configuration file, shared across users.
20+
- `user`: per-user configuration file.
21+
- `site`: per-environment configuration file; i.e. per-virtualenv.
22+
23+
### Location
24+
25+
pip's configuration files are located in fairly standard locations. This
26+
location is different on different operating systems, and has some additional
27+
complexity for backwards compatibility reasons.
28+
29+
```{tab} Unix
30+
31+
Global
32+
: {file}`/etc/pip.conf`
33+
34+
Alternatively, it may be in a "pip" subdirectory of any of the paths set
35+
in the environment variable `XDG_CONFIG_DIRS` (if it exists), for
36+
example {file}`/etc/xdg/pip/pip.conf`.
37+
38+
User
39+
: {file}`$HOME/.config/pip/pip.conf`, which respects the `XDG_CONFIG_HOME` environment variable.
40+
41+
The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`.
42+
43+
Site
44+
: {file}`$VIRTUAL_ENV/pip.conf`
45+
```
46+
47+
```{tab} MacOS
48+
49+
Global
50+
: {file}`/Library/Application Support/pip/pip.conf`
51+
52+
User
53+
: {file}`$HOME/Library/Application Support/pip/pip.conf`
54+
if directory `$HOME/Library/Application Support/pip` exists
55+
else {file}`$HOME/.config/pip/pip.conf`
56+
57+
The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`.
58+
59+
Site
60+
: {file}`$VIRTUAL_ENV/pip.conf`
61+
```
62+
63+
```{tab} Windows
64+
65+
Global
66+
: * On Windows 7 and later: {file}`C:\\ProgramData\\pip\\pip.ini`
67+
(hidden but writeable)
68+
* On Windows Vista: Global configuration is not supported.
69+
* On Windows XP:
70+
{file}`C:\\Documents and Settings\\All Users\\Application Data\\pip\\pip.ini`
71+
72+
User
73+
: {file}`%APPDATA%\\pip\\pip.ini`
74+
75+
The legacy "per-user" configuration file is also loaded, if it exists: {file}`%HOME%\\pip\\pip.ini`
76+
77+
Site
78+
: {file}`%VIRTUAL_ENV%\\pip.ini`
79+
```
80+
81+
### `PIP_CONFIG_FILE`
82+
83+
Additionally, the environment variable `PIP_CONFIG_FILE` can be used to specify
84+
a configuration file that's loaded first, and whose values are overridden by
85+
the values set in the aforementioned files. Setting this to {ref}`os.devnull`
86+
disables the loading of _all_ configuration files.
87+
88+
### Loading order
89+
90+
When multiple configuration files are found, pip combines them in the following
91+
order:
92+
93+
- `PIP_CONFIG_FILE`, if given.
94+
- Global
95+
- User
96+
- Site
97+
98+
Each file read overrides any values read from previous files, so if the
99+
global timeout is specified in both the global file and the per-user file
100+
then the latter value will be used.
101+
102+
### Naming
103+
104+
The names of the settings are derived from the long command line option.
105+
106+
As an example, if you want to use a different package index (`--index-url`) and
107+
set the HTTP timeout (`--default-timeout`) to 60 seconds, your config file would
108+
look like this:
109+
110+
```ini
111+
[global]
112+
timeout = 60
113+
index-url = https://download.zope.org/ppix
114+
```
115+
116+
### Per-command section
117+
118+
Each subcommand can be configured optionally in its own section. This overrides
119+
the global setting with the same name.
120+
121+
As an example, if you want to decrease the `timeout` to `10` seconds when
122+
running the {ref}`pip freeze`, and use `60` seconds for all other commands:
123+
124+
```ini
125+
[global]
126+
timeout = 60
127+
128+
[freeze]
129+
timeout = 10
130+
```
131+
132+
### Boolean options
133+
134+
Boolean options like `--ignore-installed` or `--no-dependencies` can be set
135+
like this:
136+
137+
```ini
138+
[install]
139+
ignore-installed = true
140+
no-dependencies = yes
141+
```
142+
143+
To enable the boolean options `--no-compile`, `--no-warn-script-location` and
144+
`--no-cache-dir`, falsy values have to be used:
145+
146+
```ini
147+
[global]
148+
no-cache-dir = false
149+
150+
[install]
151+
no-compile = no
152+
no-warn-script-location = false
153+
```
154+
155+
### Repeatable options
156+
157+
For options which can be repeated like `--verbose` and `--quiet`, a
158+
non-negative integer can be used to represent the level to be specified:
159+
160+
```ini
161+
[global]
162+
quiet = 0
163+
verbose = 2
164+
```
165+
166+
It is possible to append values to a section within a configuration file. This
167+
is applicable to appending options like `--find-links` or `--trusted-host`,
168+
which can be written on multiple lines:
169+
170+
```ini
171+
[global]
172+
find-links =
173+
http://download.example.com
174+
175+
[install]
176+
find-links =
177+
http://mirror1.example.com
178+
http://mirror2.example.com
179+
180+
trusted-host =
181+
mirror1.example.com
182+
mirror2.example.com
183+
```
184+
185+
This enables users to add additional values in the order of entry for such
186+
command line arguments.
187+
188+
## Environment Variables
189+
190+
pip's command line options can be set with environment variables using the
191+
format `PIP_<UPPER_LONG_NAME>` . Dashes (`-`) have to be replaced with
192+
underscores (`_`).
193+
194+
- `PIP_DEFAULT_TIMEOUT=60` is the same as `--default-timeout=60`
195+
- ```
196+
PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
197+
```
198+
199+
is the same as
200+
201+
```
202+
--find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
203+
```
204+
205+
Repeatable options that do not take a value (such as `--verbose`) can be
206+
specified using the number of repetitions:
207+
208+
- `PIP_VERBOSE=3` is the same as `pip install -vvv`
209+
210+
```{note}
211+
Environment variables set to an empty string (like with `export X=` on Unix) will **not** be treated as false.
212+
Use `no`, `false` or `0` instead.
213+
```
214+
215+
## Precedence / Override order
216+
217+
Command line options have override environment variables, which override the
218+
values in a configuration file. Within the configuration file, values in
219+
command-specific sections over values in the global section.
220+
221+
Examples:
222+
223+
- `--host=foo` overrides `PIP_HOST=foo`
224+
- `PIP_HOST=foo` overrides a config file with `[global] host = foo`
225+
- A command specific section in the config file `[<command>] host = bar`
226+
overrides the option with same name in the `[global]` config file section.

‎docs/html/topics/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,5 @@ This section of the documentation is currently being fleshed out. See
1212
1313
authentication
1414
caching
15+
configuration
1516
```

0 commit comments

Comments
 (0)