Configuration
=============

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.

Examples
--------

- ``--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:

.. code-block:: ini

    [global]
    timeout = 60
    index-url = http://download.zope.org/ppix

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 <./#freezing-requirements>`_) command and using
``60`` seconds for all other commands is possible with:

.. code-block:: ini

    [global]
    timeout = 60
    
    [freeze]
    timeout = 10

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

.. code-block:: ini

    [install]
    ignore-installed = true
    no-dependencies = yes

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

.. code-block:: ini

    [global]
    find-links =
        http://download.example.com

    [install]
    find-links =
        http://mirror1.example.com
        http://mirror2.example.com

Location
********

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

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

And on Windows, the configuration file is: :file:`%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::

    export PIP_DEFAULT_TIMEOUT=60
    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="http://mirror1.example.com http://mirror2.example.com"

is the same as calling::

    pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com

Configuration options
---------------------

Mirror support
**************

The `PyPI mirroring infrastructure <http://pypi.python.org/mirrors>`_ as
described in `PEP 381 <http://www.python.org/dev/peps/pep-0381/>`_ 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::

    [install]
    use-mirrors = true
    mirrors =
        http://d.pypi.python.org
        http://b.pypi.python.org