==========
Usage
==========

pip
---

Usage
*****

::

 pip <command> [options]


Options
*******

.. _`General Options`:

**General Options:**

.. pip-general-options::


.. _`Package Index Options`:

**Package Index Options:**

.. pip-index-options::


.. _`pip install`:

pip install
-----------

Usage
********

.. pip-command-usage:: install

Description
***********

.. pip-command-description:: install

Options
*******

**Install Options:**

.. pip-command-options:: install

**Other Options:**

* :ref:`Package Index Options <Package Index Options>`
* :ref:`General Options <General Options>`


.. _`pip install Examples`:

Examples
********

1) Install `SomePackage` and it's dependencies from `PyPI`_ using :ref:`Requirement Specifiers`

  ::

  $ pip install SomePackage            # latest version
  $ pip install SomePackage==1.0.4     # specific version
  $ pip install 'SomePackage>=1.0.4'     # minimum version


2) Install a list of requirements specified in a file.  See the :ref:`Cookbook entry on Requirements files <Requirements Files>`.

  ::

  $ pip install -r requirements.txt


3) Upgrade an already installed `SomePackage` to the latest from PyPI.

  ::

  $ pip install --upgrade SomePackage


4) Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.

  ::

  $ pip install -e .                     # project in current directory
  $ pip install -e path/to/project       # project in another directory


5) Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support <VCS Support>` and :ref:`Editable Installs <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
  $ pip install -e git+https://git.repo/some_repo.git@egg=subdir&subdirectory=subdir_path # install a python package from a repo subdirectory

6) 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


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


8) 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


9) Find pre-release and development versions, in addition to stable versions.  By default, pip only finds stable versions.

 ::

  $ pip install --pre SomePackage



.. _PyPI: http://pypi.python.org/pypi
.. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies


pip uninstall
-------------

Usage
*****

.. pip-command-usage:: uninstall

Description
***********

.. pip-command-description:: uninstall

Options
*******

**Uninstall Options:**

.. pip-command-options:: uninstall


**Other Options:**

* :ref:`General Options <General 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`:

pip freeze
-----------

Usage
*****

.. pip-command-usage:: freeze


Description
***********

.. pip-command-description:: freeze


Options
*******

**Freeze Options:**

.. pip-command-options:: freeze

**Other Options:**

* :ref:`General Options <General 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


2) 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-command-usage:: list

Description
***********

.. pip-command-description:: list

Options
*******

**List Options:**

.. pip-command-options:: list

**Other Options:**

* :ref:`Package Index Options <Package Index Options>`
* :ref:`General Options <General Options>`


Examples
********

1) List installed packages.

 ::

  $ pip list
  Pygments (1.5)
  docutils (0.9.1)
  Sphinx (1.1.2)
  Jinja2 (2.6)

2) 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-command-usage:: show

Description
***********

.. pip-command-description:: show


Options
*******

**Show Options:**

.. pip-command-options:: show

**Other Options:**

* :ref:`General Options <General 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 search
----------

Usage
*****

.. pip-command-usage:: search


Description
***********

.. pip-command-description:: search

Options
*******

**Search Options:**

.. pip-command-options:: search

**Other Options:**

* :ref:`General Options <General Options>`

Examples
********

1. Search for "peppercorn"

 ::

  $ pip search peppercorn
  pepperedform    - Helpers for using peppercorn with formprocess.
  peppercorn      - A library for converting a token stream into [...]

.. _`pip wheel`:

pip wheel
---------

Usage
*****

.. pip-command-usage:: wheel


Description
***********

.. pip-command-description:: wheel

.. warning::

  Currently, when ``pip wheel`` finds a wheel for one of your requirements
  already on PyPI, it does not rebuild, and it does not place the file in your
  wheelhouse dir.  There is an issue open to change this
  (https://github.com/pypa/pip/issues/1310)


Options
*******

**Wheel Options:**

.. pip-command-options:: wheel

**Other Options:**

* :ref:`Package Index Options <Package Index Options>`
* :ref:`General Options <General Options>`

Examples
********

1. Build wheels for a requirement (and all its dependencies), and then install

  ::

    $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage
    $ pip install --no-index --find-links=/tmp/wheelhouse SomePackage


pip zip
-------

Usage
*****

.. pip-command-usage:: zip

Description
***********

.. pip-command-description:: zip

Options
*******

**Zip Options:**

.. pip-command-options:: zip

**Other Options:**

* :ref:`General Options <General Options>`
