pip/docs/index.txt

pip
===

pip is a tool for installing and managing Python packages, such as those
found in the `Python Package Index <http://pypi.python.org/pypi>`_.

pip is a replacement for `easy_install
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_.  It mostly
uses the same techniques for finding packages, so packages that are
easy_installable should be pip-installable as well.  This means that
you can use ``pip install SomePackage`` instead of ``easy_install
SomePackage``.

In order to use pip, you must first install `setuptools
<http://pypi.python.org/pypi/setuptools>`_ or `distribute
<http://pypi.python.org/pypi/distribute>`_.  If you use `virtualenv
<http://www.virtualenv.org>`_, a copy of pip will be automatically be
installed in each virtual environment you create.

.. comment: split here

.. toctree::
   :maxdepth: 1

   news
   installing
   usage
   requirements
   configuration
   how-to-contribute
   running-tests

.. comment: split here

Pip Compared To easy_install
----------------------------

pip is meant to improve on easy_install.  Some of the improvements:

* All packages are downloaded before installation.  Partially-completed
  installation doesn't occur as a result.

* Care is taken to present useful output on the console.

* The reasons for actions are kept track of.  For instance, if a package is
  being installed, pip keeps track of why that package was required.

* Error messages should be useful.

* The code is relatively concise and cohesive, making it easier to use
  programmatically.

* Packages don't have to be installed as egg archives, they can be installed
  flat (while keeping the egg metadata).

* Native support for other version control systems (Git, Mercurial and Bazaar)

* Uninstallation of packages.

* Simple to define fixed sets of requirements and reliably reproduce a
  set of packages.

pip doesn't do everything that easy_install does. Specifically:

* It cannot install from eggs.  It only installs from source.  (In the
  future it would be good if it could install binaries from Windows ``.exe``
  or ``.msi`` -- binary install on other platforms is not a priority.)

* It doesn't understand Setuptools extras (like ``package[test]``).  This should
  be added eventually.

* It is incompatible with some packages that extensively customize distutils
  or setuptools in their ``setup.py`` files.

pip is complementary with `virtualenv
<http://pypi.python.org/pypi/virtualenv>`__, and it is encouraged that you use
virtualenv to isolate your installation.

Community
---------

The homepage for pip is at `pip-installer.org <http://www.pip-installer.org/>`_.
Bugs can be filed in the `pip issue tracker
<https://github.com/pypa/pip/issues/>`_.  Discussion happens on the
`virtualenv email group
<http://groups.google.com/group/python-virtualenv?hl=en>`_.

Bundles
-------

Another way to distribute a set of libraries is a bundle format (specific to
pip).  This format is not stable at this time (there simply hasn't been
any feedback, nor a great deal of thought).  A bundle file contains all the
source for your package, and you can have pip install them all together.
Once you have the bundle file further network access won't be necessary.  To
build a bundle file, do::

    $ pip bundle MyApp.pybundle MyApp

(Using a `requirements file`_ would be wise.)  Then someone else can get the
file ``MyApp.pybundle`` and run::

    $ pip install MyApp.pybundle

This is *not* a binary format.  This only packages source.  If you have binary
packages, then the person who installs the files will have to have a compiler,
any necessary headers installed, etc.  Binary packages are hard, this is
relatively easy.

Using pip with virtualenv
-------------------------

pip is most nutritious when used with `virtualenv
<http://pypi.python.org/pypi/virtualenv>`__.  One of the reasons pip
doesn't install "multi-version" eggs is that virtualenv removes much of the need
for it.  Because pip is installed by virtualenv, just use
``path/to/my/environment/bin/pip`` to install things into that
specific environment.

To tell pip to only run if there is a virtualenv currently activated,
and to bail if not, use::

    export PIP_REQUIRE_VIRTUALENV=true


Using pip with virtualenvwrapper
---------------------------------

If you are using `virtualenvwrapper
<http://www.doughellmann.com/projects/virtualenvwrapper/>`_, you might
want pip to automatically create its virtualenvs in your
``$WORKON_HOME``.

You can tell pip to do so by defining ``PIP_VIRTUALENV_BASE`` in your
environment and setting it to the same value as that of
``$WORKON_HOME``.

Do so by adding the line::

    export PIP_VIRTUALENV_BASE=$WORKON_HOME

in your .bashrc under the line starting with ``export WORKON_HOME``.

Using pip with buildout
-----------------------

If you are using `zc.buildout
<http://pypi.python.org/pypi/zc.buildout>`_ you should look at
`gp.recipe.pip <http://pypi.python.org/pypi/gp.recipe.pip>`_ as an
option to use pip and virtualenv in your buildouts.

Command line completion
-----------------------

pip comes with support for command line completion in bash and zsh and
allows you tab complete commands and options. To enable it you simply
need copy the required shell script to the your shell startup file
(e.g. ``.profile`` or ``.zprofile``) by running the special ``completion``
command, e.g. for bash::

    $ pip completion --bash >> ~/.profile

And for zsh::

    $ pip completion --zsh >> ~/.zprofile

Alternatively, you can use the result of the ``completion`` command
directly with the eval function of you shell, e.g. by adding::

    eval "`pip completion --bash`"

to your startup file.