=====
 pip
=====

--------------------------------------------------
A tool for installing and managing Python packages
--------------------------------------------------

:Author: Barry Warsaw <barry@debian.org>
:Date: 2014-06-03
:Version: 1.5.6
:Manual section: 1


SYNOPSIS
========

pip <command> [options]

pip3 <command> [options]


DESCRIPTION
===========

``pip`` is a Python package installer, recommended for installing Python
packages which are not available in the Debian archive.  It can work with
version control repositories (currently only Git, Mercurial, and Bazaar
repositories), logs output extensively, and prevents partial installs by
downloading all requirements before starting installation.

On Debian, ``pip`` is the command to use when installing packages for Python
2, while ``pip3`` is the command to use when installing packages for
Python 3.


COMMANDS
========

The command comes before any options.  The following commands are recognized:

help
    Show help for commands.

install
    Install packages.

uninstall
    Uninstall packages.

freeze
    Output installed packages in requirements format.

list
    List installed packages.

show
    Show information about installed packages.

search
    Search PyPI for packages.

wheel
    Build wheels from your requirements.


GENERAL OPTIONS
===============

This list is by no means complete, and it only describes options available to
all commands.  Use ``pip <command> --help`` for more details on command
specific options.  A few command options are provided below.

-h, --help
    Show more detailed command 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 <path>
    Path to a verbose non-appending log, that only logs failures.  This log is
    active by default at `~/.pip/pip.log`.

--log <path>
    Path to a verbose appending log.  This log is inactive by default.

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


INSTALL OPTIONS
===============

``pip install`` installs packages from:

 * PyPI (a.k.a. The Cheeseshop) and other indexes, using requirements
   specifiers.
 * VCS project urls.
 * Local project directories.
 * Local or remote source archives

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

--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 packages as eggs, not 'flat', like pip normally does. This option
    is not about installing *from* eggs. (WARNING: Because this option
    overrides pip's normal install logic, requirements files may not behave as
    expected.)

--root <dir>
    Install everything relative to this alternate root directory.

--compile
    Compile py files to pyc.

--no-compile
    Do not compile py files to pyc.

--no-use-wheel
    Do not find and prefer wheel archives when searching indexes and
    find-links locations.

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

--no-clean
    Don't clean up build directories.

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.

--allow-external <package>
    Allow the installation of externally hosted files

--allow-all-external
    Allow the installation of all externally hosted files

--allow-unverified <package>
    Allow the installation of insecure and unverifiable files

--process-dependency-links
    Enable the processing of dependency links.


UNINSTALL OPTIONS
=================

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

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


AUTHORS
=======

This manual page was originally written by Jeff Licquia <licquia@debian.org>,
later rewritten by Carl Chenet <chaica@debian.org>.  It was rewritten again
and the source converted to reStructuredText by Barry Warsaw
<barry@debian.org>.

Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU General Public License, version 3 or any later version
published by the Free Software Foundation.