pip allows a user to change its behaviour via 3 mechanisms:
command line options
environment variables
configuration files
This page explains how the configuration files and environment variables work,and how they are related to pip’s various command line options.
See also
pip config command, which helps manage pip’s configuration.
Configuration Files¶
Configuration files can change the default values for command line options.The files are written using standard INI format.
pip has 3 “levels” of configuration files:
global: system-wide configuration file, shared across users.user: per-user configuration file.site: per-environment configuration file; i.e. per-virtualenv.
Additionally, environment variables can be specified which will override any of the above.
Location¶
pip’s configuration files are located in fairly standard locations. Thislocation is different on different operating systems, and has some additionalcomplexity for backwards compatibility reasons. Note that if user config filesexist in both the legacy and current locations, values in the current filewill override values in the legacy file.
- Global
In a “pip” subdirectory of any of the paths set in the environment variable
XDG_CONFIG_DIRS(if it exists), for example/etc/xdg/pip/pip.conf.This will be followed by loading
/etc/pip.conf.- User
$HOME/.config/pip/pip.conf, which respects theXDG_CONFIG_HOMEenvironment variable.The legacy “per-user” configuration file is also loaded, if it exists:
$HOME/.pip/pip.conf.- Site
$VIRTUAL_ENV/pip.conf
- Global
/Library/Application Support/pip/pip.conf- User
$HOME/Library/Application Support/pip/pip.confif directory$HOME/Library/Application Support/pipexistselse$HOME/.config/pip/pip.confThe legacy “per-user” configuration file is also loaded, if it exists:
$HOME/.pip/pip.conf.- Site
$VIRTUAL_ENV/pip.conf
- Global
On Windows 7 and later:
C:\ProgramData\pip\pip.ini(hidden but writeable)On Windows Vista: Global configuration is not supported.
On Windows XP:
C:\Documents and Settings\All Users\Application Data\pip\pip.ini
- User
%APPDATA%\pip\pip.iniThe legacy “per-user” configuration file is also loaded, if it exists:
%HOME%\pip\pip.ini- Site
%VIRTUAL_ENV%\pip.ini
PIP_CONFIG_FILE¶
Additionally, the environment variable PIP_CONFIG_FILE can be used to specifya configuration file that’s loaded last, and whose values override the valuesset in the aforementioned files. Setting this to os.devnulldisables the loading of all configuration files. Note that if a file existsat the location that this is set to, the user config file will not be loaded.
Loading order¶
When multiple configuration files are found, pip combines them in the followingorder:
Global
User
Site
PIP_CONFIG_FILE, if given.
Each file read overrides any values read from previous files, so if theglobal timeout is specified in both the global file and the per-user filethen the latter value will be used.
Naming¶
The names of the settings are derived from the long command line option.
As an example, if you want to use a different package index (--index-url) andset the HTTP timeout (--timeout) to 60 seconds, your config file wouldlook like this:
[global]timeout = 60index-url = https://download.zope.org/ppix
Per-command section¶
Each subcommand can be configured optionally in its own section. This overridesthe global setting with the same name.
As an example, if you want to decrease the timeout to 10 seconds whenrunning the pip freeze, and use 60 seconds for all other commands:
[global]timeout = 60[freeze]timeout = 10
Boolean options¶
Boolean options like --ignore-installed or --no-dependencies can be setlike this:
[install]ignore-installed = trueno-dependencies = yes
To enable the boolean options --no-compile, --no-warn-script-location and--no-cache-dir, falsy values have to be used:
[global]no-cache-dir = false[install]no-compile = nono-warn-script-location = false
Repeatable options¶
For options which can be repeated like --verbose and --quiet, anon-negative integer can be used to represent the level to be specified:
[global]quiet = 0verbose = 2
It is possible to append values to a section within a configuration file. Thisis applicable to appending options like --find-links or --trusted-host,which can be written on multiple lines:
[global]find-links = http://download.example.com[install]find-links = http://mirror1.example.com http://mirror2.example.comtrusted-host = mirror1.example.com mirror2.example.com
This enables users to add additional values in the order of entry for suchcommand line arguments.
Environment Variables¶
pip’s command line options can be set with environment variables using theformat PIP_<UPPER_LONG_NAME> . Dashes (-) have to be replaced withunderscores (_).
PIP_TIMEOUT=60is the same as--timeout=60PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
is the same as
--find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
Repeatable options that do not take a value (such as --verbose) can bespecified using the number of repetitions:
PIP_VERBOSE=3is the same aspip install -vvv
Note
Environment variables set to an empty string (like with export X= on Unix) will not be treated as false.Use no, false or 0 instead.
Precedence / Override order¶
Command line options override environment variables, which override thevalues in a configuration file. Within the configuration file, values incommand-specific sections override values in the global section.
Examples:
--host=foooverridesPIP_HOST=fooPIP_HOST=foooverrides a config file with[global] host = fooA command specific section in the config file
[<command>] host = baroverrides the option with same name in the[global]config file section.
