============================
Installing the Package Tools
============================

In the :ref:`current state of packaging <state_of_packaging_info>` in Python,
one needs a set of tools to easily manipulate the packaging ecosystem. There are
two tools in particular that are extremely handy in the current ecosystem. There
is a third tool, :doc:`virtualenv`, that will be discussed later in this
documentation that will assist in isolating a packaging ecosystem from the
global one. The combination of these tools will help to find, install and
uninstall packages.

.. _distribute_info:

Distribute
==========

.. _Distribute: http://packages.python.org/distribute

Distribute_ is a collection of enhancements to the Python standard library
module: :mod:`distutils` (for Python 2.3.5 and up on most platforms; 64-bit
platforms require a minimum of Python 2.4) that allows you to more easily build
and distribute Python packages, especially ones that have dependencies on other
packages.

Distribute was created because the `Setuptools package
<http://pypi.python.org/pypi/setuptools/>`_ is no longer maintained. Third-party
packages will likely require :mod:`setuptools`, which is provided by the
Distribute_ package. Therefore, anytime time a packages depends on the
`Setuptools package <http://pypi.python.org/pypi/setuptools/>`_, Distribute_
will step in to say it already provides the :mod:`setuptools` module.

.. seealso:: `Distribute documentation <http://packages.python.org/distribute>`_.

Installation Instructions
-------------------------

Distribute_ can be installed using the `distribute_setup.py
<http://python-distribute.org/distribute_setup.py>`_ script.  It can also be
installed using easy_install, pip, the source tarball, or the egg distribution.
`distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_ is the
simplest and preferred way to install Distribute on all systems.

Download `distribute_setup.py
<http://python-distribute.org/distribute_setup.py>`_ and execute it, using the
Python interpreter of your choice.

From the \*nix shell you can do::

    $ wget http://python-distribute.org/distribute_setup.py
    $ python distribute_setup.py

.. note:: For those on Mac OS X, you can use ``curl -O <url>`` instead of
   ``wget``.

.. seealso:: The development version of Distribute can be found at:
   http://bitbucket.org/tarek/distribute/

.. _pip_info:

Pip Installs Python (Pip)
=========================

`Pip`_ is an installer for Python packages written by Ian Bicking. It
can install packages, list installed packages, upgrade packages and
uninstall packages.

The ``pip`` application is a replacement for `easy_install
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_. It uses mostly the
same techniques for finding packages, so packages that were made
easy_installable should be pip-installable as well.

.. seealso:: `Pip Documentation <http://pip.openplans.org/index.html>`_ and `Pip
   PyPI description <http://pypi.python.org/pypi/pip>`_

.. note:: ??? `Pip requirements <http://pip.openplans.org/#requirements-files>`_

Installing Pip
--------------

The `Pip`_ installer can be installed using the source tarball or using
``easy_install``.  The source tarball is the recommended method of installation.

The latest version of the source tarball can be obtained from PyPI::

    $ wget http://pypi.python.org/packages/source/p/pip/pip-0.7.2.tar.gz
    $ tar xzf pip-0.7.2.tar.gz
    $ cd pip-0.7.2
    $ python setup.py install

Or the ``easy_install`` application can be used::

    $ easy_install pip

The ``pip`` application is now installed.

.. Can the above be simplified?

.. note:: ``pip`` is complementary with :doc:`virtualenv`, and it is encouraged
   that you use :doc:`virtualenv` to isolate your installation.

Installing a package
--------------------

Let's install the `Markdown`_ package::

    $ pip install Markdown

Markdown is now installed; you can import and use it::

    $ python -c "import markdown; print markdown.markdown('**Excellent**')"

Listing installed packages
--------------------------

To list installed packages and versions, use the ``freeze`` command::

    $ pip freeze
    Markdown==2.0.3
    wsgiref==0.1.2

.. Note::
   The ``wsgiref`` package is a part of the Python standard
   library. Currently it is the only standard library package that
   includes `package metadata`_, so it is the only standard library
   package whose presence pip reports.

Installing specific versions
----------------------------

You can also give pip a version specifier for a package using one or
more of ==, >=, >, <, <=::

    $ pip install 'Markdown<2.0'

This will find your current installation of Markdown 2.0.3,
automatically uninstall it, and install Markdown 1.7 (the latest
version in the 1.x series) in its place. You can even combine version
specifiers with a comma::

    $ pip install 'Markdown>2.0,<2.0.3'

Upgrading
---------

If you want to upgrade a package to its most recent available version, use the
``-U`` or ``--upgrade`` flag::

    $ pip install -U Markdown

Uninstalling
------------

Now let's uninstall Markdown::

    $ pip uninstall Markdown

After showing you which files/directories will be removed and
requesting confirmation, pip will uninstall everything installed by
the Markdown package.

.. Note::
   Pip inside a :doc:`Virtual Environment <virtualenv>` will only uninstall
   packages installed within that virtual environment. For instance, if you try
   to ``pip uninstall wsgiref`` it will refuse, because the reference is within
   the global Python's standard library.

.. _Pip: http://pip.openplans.org/
.. _Markdown: http://pypi.python.org/pypi/Markdown
.. _package metadata: http://www.python.org/dev/peps/pep-0314/
.. _Python Package Index: http://pypi.python.org/pypi/