pip allows you to set its default options by using the following facilities, in the order of each item’s importance:

  1. Command line options
  2. Environment variables
  3. Config files
    1. Command specific section, e.g. [install]
    2. Global section [global]

That means it will check each of those configuration sources and set the defaults appropriately.


  • --host=foo overrides PIP_HOST=foo
  • PIP_HOST=foo overrides a config file with [global] host = foo
  • A command specific section in the config file [<command>] host = bar overrides the option with same name in the [global] config file section
  • Environment variables override config files

Config files

pip allows you to set all command line option defaults in a standard ini style config file.

The names of the settings are derived from the long command line option, e.g. if you want to use a different package index (--index-url) and set the HTTP timeout (--default-timeout) to 60 seconds your config file would look like this:

timeout = 60
index-url =

Each subcommand can be configured optionally in its own section so that every global setting with the same name will be overridden; e.g. decreasing the timeout to 10 seconds when running the freeze (Freezing Requirements) command and using 60 seconds for all other commands is possible with:

timeout = 60

timeout = 10

Boolean options like --ignore-installed or --no-dependencies can be set like this:

ignore-installed = true
no-dependencies = yes

Appending options like --find-links can be written on multiple lines:

find-links =

find-links =


The names and locations of the configuration files vary slightly across platforms.

On Unix and Mac OS X the configuration file is: $HOME/.pip/pip.conf

And on Windows, the configuration file is: %HOME%\pip\pip.ini

Environment variables

Just like with config files, each of pip’s command line options (long version, e.g. --find-links) are automatically set by looking for environment variables with the name format PIP_<UPPER_NAME>. That means the name of the command line options are capitalized and have dashes (-) replaced with underscores (_).

For example, to redefine the default timeout you can also set an environment variable:

pip install ipython

Which is the same as passing the option to pip directly:

pip --default-timeout=60 install ipython

This also works for appending command line options, like --find-links. Just leave an empty space between the passsed values, e.g.:

export PIP_FIND_LINKS=""

is the same as calling:

pip install --find-links= --find-links=

Configuration options

Mirror support

The PyPI mirroring infrastructure as described in PEP 381 can be used by passing the --use-mirrors option to the install command. Alternatively, you can use the other ways to configure pip, e.g.:

$ export PIP_USE_MIRRORS=true

If enabled, pip will automatically query the DNS entry of the mirror index URL to find the list of mirrors to use. In case you want to override this list, please use the --mirrors option of the install command, or add to your pip configuration file:

use-mirrors = true
mirrors =

Table Of Contents

Previous topic

Requirements files

Next topic

Relationship with other tools

This Page