pip — pip 8.1.2 documentation

# pip

Contents

- pip
  - Usage
  - Description
    - Logging
      - Console logging
      - File logging
    - --exists-action option
    - Build System Interface
      - Setuptools Injection
      - Future Developments
      - Build Options
  - General Options

## Usage

    pip <command> [options]

## Description

### Logging

#### Console logging

pip offers -v, --verbose and -q, --quiet to control the console log level.

#### File logging

pip offers the --log option for specifying a file where a maximum verbosity log will be kept. This option is empty by default. This log appends to previous logging.

Like all pip options, `--log` can also be set as an environment variable, or placed into the pip config file. See the Configuration section.

### --exists-action option

This option specifies default behavior when path already exists. Possible cases: downloading files or checking out repositories for installation, creating archives. If `--exists-action` is not defined, pip will prompt when decision is needed.

(s)witch
  Only relevant to VCS checkout. Attempt to switch the checkout to the appropriate url and/or revision.
(i)gnore
  Abort current operation (e.g. don't copy file, don't create archive, don't modify a checkout).
(w)ipe
  Delete the file or VCS checkout before trying to create, download, or checkout a new one.
(b)ackup
  Rename the file or checkout to `{name}{'.bak' * n}`, where n is some number of `.bak` extensions, such that the file didn't exist at some point. So the most recent backup will be the one with the largest number after `.bak`.

### Build System Interface

Pip builds packages by invoking the build system. Presently, the only supported build system is `setuptools`, but future developments to the Python packaging infrastructure are expected to include support for other build systems. As well as package building, the build system is also invoked to install packages direct from source.

The interface to the build system is via the `setup.py` command line script - all build actions are defined in terms of the specific `setup.py` command line that will be run to invoke the required action.

#### Setuptools Injection

As noted above, the supported build system is `setuptools`. However, not all packages use `setuptools` in their build scripts. To support projects that use "pure `distutils`", pip injects `setuptools` into `sys.modules` before invoking `setup.py`. The injection should be transparent to `distutils`-based projects, but 3rd party build tools wishing to provide a `setup.py` emulating the commands pip requires may need to be aware that it takes place.

#### Future Developments

PEP426 notes that the intention is to add hooks to project metadata in version 2.1 of the metadata spec, to explicitly define how to build a project from its source. Once this version of the metadata spec is final, pip will migrate to using that interface. At that point, the `setup.py` interface documented here will be retained solely for legacy purposes, until projects have migrated.

Specifically, applications should not expect to rely on there being any form of backward compatibility guarantees around the `setup.py` interface.

#### Build Options

The `--global-option` and `--build-option` arguments to the `pip install` and `pip wheel` inject additional arguments into the `setup.py` command (`--build-option` is only available in `pip wheel`). These arguments are included in the command as follows:

    python setup.py <global_options> BUILD COMMAND <build_options>

The options are passed unmodified, and presently offer direct access to the distutils command line. Use of `--global-option` and `--build-option` should be considered as build system dependent, and may not be supported in the current form if support for alternative build systems is added to pip.

## General Options

`-h````,` `--help```

  Show help.

`--isolated```

  Run pip in an isolated mode, ignoring environment variables and user configuration.

`-v````,` `--verbose```

  Give more output. Option is additive, and can be used up to 3 times.

`-V````,` `--version```

  Show version and exit.

`-q````,` `--quiet```

  Give less output.

`--log``<path>`

  Path to a verbose appending log.

`--proxy``<proxy>`

  Specify a proxy in the form [user:passwd@]proxy.server:port.

`--retries``<retries>`

  Maximum number of retries each connection should attempt (default 5 times).

`--timeout``<sec>`

  Set the socket timeout (default 15 seconds).

`--exists-action``<action>`

  Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup.

`--trusted-host``<hostname>`

  Mark this host as trusted, even though it does not have valid or any HTTPS.

`--cert``<path>`

  Path to alternate CA bundle.

`--client-cert``<path>`

  Path to SSL client certificate, a single file containing the private key and the certificate in PEM format.

`--cache-dir``<dir>`

  Store the cache data in <dir>.

`--no-cache-dir```

  Disable the cache.

`--disable-pip-version-check```

  Don't periodically check PyPI to determine whether a new version of pip is available for download. Implied with --no-index.