Usage

General Options:

-h, --help

Show help.

-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 <file>

Log file where a complete (maximum verbosity) record will be kept.

--proxy <proxy>

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

--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.

--cert <path>

Path to alternate CA bundle.

Package Index Options:

-i, --index-url <url>

Base URL of Python Package Index (default https://pypi.python.org/simple/).

--extra-index-url <url>

Extra URLs of package indexes to use in addition to –index-url.

--no-index

Ignore package index (only looking at –find-links URLs instead).

-f, --find-links <url>

If a url or path to an html file, then parse for links to archives. If a local path or file:// url that’s a directory, then look for archives in the directory listing.

-M, --use-mirrors

Use the PyPI mirrors as a fallback in case the main index is down.

--mirrors <url>

Specific mirror URLs to query when –use-mirrors is used.

--allow-external <package>

Allow the installation of externally hosted files

--allow-all-external

Allow the installation of all externally hosted files

--no-allow-external

Disallow the installation of all externally hosted files

--allow-insecure <package>

Allow the installation of insecure and unverifiable files

--no-allow-insecure

Disallow the installation of insecure and unverifiable files

pip install

Usage

pip install [options] <requirement specifier> ...
pip install [options] -r <requirements file> ...
pip install [options] [-e] <vcs project url> ...
pip install [options] [-e] <local project path> ...
pip install [options] <archive url/path> ...

Description

Install packages from:

  • PyPI (and other indexes) using requirement specifiers.
  • VCS project urls.
  • Local project directories.
  • Local or remote source archives.

pip also supports installing from “requirements files”, which provide an easy way to specify a whole environment to be installed.

See http://www.pip-installer.org for details on VCS url formats and requirements files.

Options

Install Options:

-e, --editable <path/url>

Install a project in editable mode (i.e. setuptools “develop mode”) from a local project path or a VCS url.

-r, --requirement <file>

Install from the given requirements file. This option can be used multiple times.

-b, --build <dir>

Directory to unpack packages into and build in. The default in a virtualenv is “<venv path>/build”. The default for global installs is “<OS temp dir>/pip-build-<username>”.

-t, --target <dir>

Install packages into <dir>.

-d, --download <dir>

Download packages into <dir> instead of installing them, regardless of what’s already installed.

--download-cache <dir>

Cache downloaded packages in <dir>.

--src <dir>

Directory to check out editable projects into. The default in a virtualenv is “<venv path>/src”. The default for global installs is “<current dir>/src”.

-U, --upgrade

Upgrade all packages to the newest available version. This process is recursive regardless of whether a dependency is already satisfied.

--force-reinstall

When upgrading, reinstall all packages even if they are already up-to-date.

-I, --ignore-installed

Ignore the installed packages (reinstalling instead).

--no-deps

Don’t install package dependencies.

--no-install

Download and unpack all packages, but don’t actually install them.

--no-download

Don’t download any packages, just install the ones already downloaded (completes an install run with –no-install).

--install-option <options>

Extra arguments to be supplied to the setup.py install command (use like –install-option=”–install-scripts=/usr/local/bin”). Use multiple –install-option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path.

--global-option <options>

Extra global options to be supplied to the setup.py call before the install command.

--user

Install using the user scheme.

--egg

Install as self contained egg file, like easy_install does.

--root <dir>

Install everything relative to this alternate root directory.

--use-wheel

Find and prefer wheel archives when searching indexes and find-links locations. Default to accepting source archives.

--pre

Include pre-release and development versions. By default, pip only finds stable versions.

--no-clean

Don’t clean up build directories.

Other Options:

Examples

  1. Install SomePackage and it’s dependencies from PyPI using Requirement Specifiers
$ pip install SomePackage            # latest version
$ pip install SomePackage==1.0.4     # specific version
$ pip install 'SomePackage>=1.0.4'     # minimum version
  1. Install a list of requirements specified in a file. See the Cookbook entry on Requirements files.
$ pip install -r requirements.txt
  1. Upgrade an already installed SomePackage to the latest from PyPI.
$ pip install --upgrade SomePackage
  1. Install a local project in “editable” mode. See the section on Editable Installs.
$ pip install -e .                     # project in current directory
$ pip install -e path/to/project       # project in another directory
  1. Install a project from VCS in “editable” mode. See the sections on VCS Support and Editable Installs.
$ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage          # from git
$ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage            # from mercurial
$ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage         # from svn
$ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage  # from 'feature' branch
  1. Install a package with setuptools extras.
$ pip install SomePackage[PDF]
$ pip install SomePackage[PDF]==3.0
$ pip install -e .[PDF]==3.0  # editable project in current directory
  1. Install a particular source archive file.
$ pip install ./downloads/SomePackage-1.0.4.tar.gz
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
  1. Install from alternative package repositories.

Install from a different index, and not PyPI:

$ pip install --index-url http://my.package.repo/simple/ SomePackage

Search an additional index during install, in addition to PyPI:

$ pip install --extra-index-url http://my.package.repo/simple SomePackage

Install from a local flat directory containing archives (and don’t scan indexes):

$ pip install --no-index --find-links:file:///local/dir/ SomePackage
$ pip install --no-index --find-links:/local/dir/ SomePackage
$ pip install --no-index --find-links:relative/dir/ SomePackage
  1. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.
$ pip install --pre SomePackage

pip uninstall

Usage

pip uninstall [options] <package> ...
pip uninstall [options] -r <requirements file> ...

Description

Uninstall packages.

pip is able to uninstall most installed packages. Known exceptions are:

  • Pure distutils packages installed with python setup.py install, which leave behind no metadata to determine what files were installed.
  • Script wrappers installed by python setup.py develop.

Options

Uninstall Options:

-r, --requirement <file>

Uninstall all the packages listed in the given requirements file. This option can be used multiple times.

-y, --yes

Don’t ask for confirmation of uninstall deletions.

Other Options:

Examples

  1. Uninstall a package.
$ pip uninstall simplejson
Uninstalling simplejson:
  /home/me/env/lib/python2.7/site-packages/simplejson
  /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info
Proceed (y/n)? y
  Successfully uninstalled simplejson

pip freeze

Usage

pip freeze [options]

Description

Output installed packages in requirements format.

Options

Freeze Options:

-r, --requirement <file>

Use the order in the given requirements file and it’s comments when generating output.

-f, --find-links <url>

URL for finding packages, which will be added to the output.

-l, --local

If in a virtualenv that has global access, do not output globally-installed packages.

Other Options:

Examples

  1. Generate output suitable for a requirements file.
$ pip freeze
Jinja2==2.6
Pygments==1.5
Sphinx==1.1.3
docutils==0.9.1
  1. Generate a requirements file and then install from it in another environment.
$ env1/bin/pip freeze > requirements.txt
$ env2/bin/pip install -r requirements.txt

pip list

Usage

pip list [options]

Description

List installed packages, including editables.

Options

List Options:

-o, --outdated

List outdated packages (excluding editables)

-u, --uptodate

List uptodate packages (excluding editables)

-e, --editable

List editable projects.

-l, --local

If in a virtualenv that has global access, do not list globally-installed packages.

--pre

Include pre-release and development versions. By default, pip only finds stable versions.

Other Options:

Examples

  1. List installed packages.
$ pip list
Pygments (1.5)
docutils (0.9.1)
Sphinx (1.1.2)
Jinja2 (2.6)
  1. List outdated packages (excluding editables), and the latest version available
$ pip list --outdated
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)

pip show

Usage

pip show [options] <package> ...

Description

Show information about one or more installed packages.

Options

Show Options:

-f, --files

Show the full list of installed files for each package.

Other Options:

Examples

  1. Show information about a package:
$ pip show sphinx
---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils

pip wheel

Usage

pip wheel [options] <requirement specifier> ...
pip wheel [options] -r <requirements file> ...
pip wheel [options] <vcs project url> ...
pip wheel [options] <local project path> ...
pip wheel [options] <archive url/path> ...

Description

Build Wheel archives for your requirements and dependencies.

Wheel is a built-package format, and offers the advantage of not recompiling your software during every install. For more details, see the wheel docs: http://wheel.readthedocs.org/en/latest.

Requirements: setuptools>=0.8, and wheel.

‘pip wheel’ uses the bdist_wheel setuptools extension from the wheel package to build individual wheels.

Options

Wheel Options:

-w, --wheel-dir <dir>

Build wheels into <dir>, where the default is ‘<cwd>/wheelhouse’.

--use-wheel

Find and prefer wheel archives when searching indexes and find-links locations. Default to accepting source archives.

--build-option <options>

Extra arguments to be supplied to ‘setup.py bdist_wheel’.

-r, --requirement <file>

Install from the given requirements file. This option can be used multiple times.

--download-cache <dir>

Cache downloaded packages in <dir>.

--no-deps

Don’t install package dependencies.

-b, --build <dir>

Directory to unpack packages into and build in. The default in a virtualenv is “<venv path>/build”. The default for global installs is “<OS temp dir>/pip-build-<username>”.

--global-option <options>

Extra global options to be supplied to the setup.py call before the ‘bdist_wheel’ command.

--pre

Include pre-release and development versions. By default, pip only finds stable versions.

--no-clean

Don’t clean up build directories.

Other Options:

Examples

  1. Build wheels for a requirement (and all its dependencies), and then install
$ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage
$ pip install --use-wheel --no-index --find-links=/tmp/wheelhouse SomePackage

pip zip

Usage

pip zip [options] <package> ...

Description

Zip individual packages.

Options

Zip Options:

--unzip

Unzip (rather than zip) a package.

--no-pyc

Do not include .pyc files in zip files (useful on Google App Engine).

-l, --list

List the packages available, and their zip status.

--sort-files

With –list, sort packages according to how many files they contain.

--path <paths>

Restrict operations to the given paths (may include wildcards).

-n, --simulate

Do not actually perform the zip/unzip operation.

Other Options: