2008-10-16 00:24:00 +02:00
|
|
|
pip
|
|
|
|
===
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2009-04-03 23:20:20 +02:00
|
|
|
pip installs Python packages. It is a replacement for
|
|
|
|
``easy_install``. Documentation follows; to download `visit the PyPI
|
|
|
|
entry <http://pypi.python.org/pypi/pip>`_ (or the `repository
|
|
|
|
<http://bitbucket.org/ianb/pip/>`_).
|
|
|
|
|
2008-10-16 00:02:57 +02:00
|
|
|
.. toctree::
|
|
|
|
|
|
|
|
news
|
|
|
|
requirement-format
|
2009-10-25 02:22:53 +01:00
|
|
|
configuration
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
.. comment: split here
|
|
|
|
|
|
|
|
Introduction
|
|
|
|
------------
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip is a replacement for `easy_install
|
2008-10-16 00:02:57 +02:00
|
|
|
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_. It uses mostly the
|
|
|
|
same techniques for finding packages, so packages that were made
|
2008-10-31 19:39:22 +01:00
|
|
|
easy_installable should be pip-installable as well.
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip is meant to improve on easy_install. Some of the improvements:
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
* 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
|
2008-10-16 00:24:00 +02:00
|
|
|
being installed, pip keeps track of why that package was required.
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
* 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).
|
|
|
|
|
2009-01-21 15:39:50 +01:00
|
|
|
* Native support for other version control systems (Git, Mercurial and Bazaar)
|
|
|
|
|
2009-10-02 20:06:26 +02:00
|
|
|
* Uninstallation of packages.
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2009-10-02 20:06:26 +02:00
|
|
|
* Simple to define fixed sets of requirements and reliably reproduce a
|
|
|
|
set of packages.
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip is complementary with `virtualenv
|
2008-10-16 00:02:57 +02:00
|
|
|
<http://pypi.python.org/pypi/virtualenv>`_, and it is encouraged that you use
|
|
|
|
virtualenv to isolate your installation.
|
|
|
|
|
|
|
|
Community
|
|
|
|
---------
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
The homepage for pip is temporarily located `on PyPI
|
2009-01-21 19:12:04 +01:00
|
|
|
<http://pypi.python.org/pypi/pip>`_ -- a more proper homepage will
|
|
|
|
follow. Bugs can go on the `pip Trac instance
|
|
|
|
<http://oss.openplans.org/pip/>`_. Discussion should happen on the
|
|
|
|
`virtualenv email group
|
2008-10-16 00:02:57 +02:00
|
|
|
<http://groups.google.com/group/python-virtualenv?hl=en>`_.
|
|
|
|
|
|
|
|
Differences From easy_install
|
|
|
|
-----------------------------
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip cannot install some packages. Specifically:
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
* It cannot install from eggs. It only installs from source. (Maybe this will
|
|
|
|
be changed sometime, but it's low priority.)
|
|
|
|
|
|
|
|
* It doesn't understand Setuptools extras (like ``package[test]``). This should
|
|
|
|
be added eventually.
|
|
|
|
|
|
|
|
* It is incompatible with some packages that customize distutils or setuptools
|
|
|
|
in their ``setup.py`` files.
|
|
|
|
|
|
|
|
* Maybe it doesn't work on Windows. At least, the author doesn't test on
|
|
|
|
Windows often.
|
|
|
|
|
|
|
|
* It also has some extra features. Extra features the author thinks are great.
|
|
|
|
|
2009-10-02 20:06:26 +02:00
|
|
|
Uninstall
|
|
|
|
---------
|
|
|
|
|
|
|
|
pip is able to uninstall most installed packages with ``pip uninstall
|
|
|
|
package-name``.
|
|
|
|
|
|
|
|
Known exceptions include pure-distutils packages installed with
|
|
|
|
``python setup.py install`` (such packages leave behind no metadata allowing
|
|
|
|
determination of what files were installed), and script wrappers installed
|
|
|
|
by develop-installs (``python setup.py develop``).
|
|
|
|
|
|
|
|
pip also performs an automatic uninstall of an old version of a package
|
|
|
|
before upgrading to a newer version, so outdated files (and egg-info data)
|
|
|
|
from conflicting versions aren't left hanging around to cause trouble. The
|
|
|
|
old version of the package is automatically restored if the new version
|
|
|
|
fails to download or install.
|
|
|
|
|
2008-10-16 00:02:57 +02:00
|
|
|
.. _`requirements file`:
|
|
|
|
|
|
|
|
Requirements Files
|
|
|
|
------------------
|
|
|
|
|
|
|
|
When installing software, and Python packages in particular, it's common that
|
|
|
|
you get a lot of libraries installed. You just did ``easy_install MyPackage``
|
|
|
|
and you get a dozen packages. Each of these packages has its own version.
|
|
|
|
|
|
|
|
Maybe you ran that installation and it works. Great! Will it keep working?
|
|
|
|
Did you have to provide special options to get it to find everything? Did you
|
|
|
|
have to install a bunch of other optional pieces? Most of all, will you be able
|
|
|
|
to do it again?
|
|
|
|
|
|
|
|
If you've ever tried to setup an application on a new system, or with slightly
|
2008-10-16 00:24:00 +02:00
|
|
|
updated pieces, and had it fail, pip requirements are for you. If you
|
|
|
|
haven't had this problem then you will eventually, so pip requirements are
|
2008-10-16 00:02:57 +02:00
|
|
|
for you too -- requirements make explicit, repeatable installation of packages.
|
|
|
|
|
|
|
|
So what are requirements files? They are very simple: lists of packages to
|
2008-10-16 00:24:00 +02:00
|
|
|
install. Instead of running something like ``pip MyApp`` and getting
|
2008-10-16 00:02:57 +02:00
|
|
|
whatever libraries come along, you can create a requirements file something like::
|
|
|
|
|
|
|
|
MyApp
|
|
|
|
Framework==0.9.4
|
|
|
|
Library>=0.2
|
|
|
|
|
|
|
|
Then, regardless of what MyApp lists in ``setup.py``, you'll get a specific
|
|
|
|
version of Framework and at least the 0.2 version of Library. (You might think
|
|
|
|
you could list these specific versions in ``setup.py`` -- try it and you'll
|
|
|
|
quickly see why that doesn't work.) You can add optional libraries and support
|
|
|
|
tools that MyApp doesn't strictly require.
|
|
|
|
|
|
|
|
You can also include "editable" packages -- packages that are checked out from
|
2009-01-21 03:49:40 +01:00
|
|
|
Subversion, Git, Mercurial and Bazaar. These are just like using the ``-e``
|
|
|
|
option to pip. They look like::
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
-e svn+http://myrepo/svn/MyApp#egg=MyApp
|
|
|
|
|
2009-03-13 13:01:58 +01:00
|
|
|
You have to start the URL with ``svn+`` (``git+``, ``hg+`` or ``bzr+``), and
|
2009-01-21 03:49:40 +01:00
|
|
|
you have to include ``#egg=Package`` so pip knows what to expect at that URL.
|
2009-01-09 11:18:23 +01:00
|
|
|
You can also include ``@rev`` in the URL, e.g., ``@275`` to check out
|
|
|
|
revision 275.
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
Freezing Requirements
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
So you have a working set of packages, and you want to be able to install them
|
|
|
|
elsewhere. `Requirements files`_ let you install exact versions, but it won't
|
|
|
|
tell you what all the exact versions are.
|
|
|
|
|
|
|
|
To create a new requirements file from a known working environment, use::
|
|
|
|
|
2009-06-13 14:44:32 +02:00
|
|
|
$ pip freeze > stable-req.txt
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
This will write a listing of *all* installed libraries to ``stable-req.txt``
|
|
|
|
with exact versions for every library. You may want to edit the file down after
|
|
|
|
generating (e.g., to eliminate unnecessary libraries), but it'll give you a
|
|
|
|
stable starting point for constructing your requirements file.
|
|
|
|
|
|
|
|
You can also give it an existing requirements file, and it will use that as a
|
|
|
|
sort of template for the new file. So if you do::
|
|
|
|
|
2009-06-13 14:44:32 +02:00
|
|
|
$ pip freeze -r devel-req.txt > stable-req.txt
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
it will keep the packages listed in ``devel-req.txt`` in order and preserve
|
|
|
|
comments.
|
|
|
|
|
|
|
|
Bundles
|
|
|
|
-------
|
|
|
|
|
|
|
|
Another way to distribute a set of libraries is a bundle format (specific to
|
2008-10-16 00:24:00 +02:00
|
|
|
pip). This format is not stable at this time (there simply hasn't been
|
2008-10-16 00:02:57 +02:00
|
|
|
any feedback, nor a great deal of thought). A bundle file contains all the
|
2008-10-31 19:39:22 +01:00
|
|
|
source for your package, and you can have pip install them all together.
|
2008-10-16 00:02:57 +02:00
|
|
|
Once you have the bundle file further network access won't be necessary. To
|
|
|
|
build a bundle file, do::
|
|
|
|
|
2009-02-04 19:44:51 +01:00
|
|
|
$ pip bundle MyApp.pybundle MyApp
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
(Using a `requirements file`_ would be wise.) Then someone else can get the
|
|
|
|
file ``MyApp.pybundle`` and run::
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
$ pip install MyApp.pybundle
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
Using pip With virtualenv
|
|
|
|
-------------------------
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip is most nutritious when used with `virtualenv
|
|
|
|
<http://pypi.python.org/pypi/virtualenv>`_. One of the reasons pip
|
2008-10-16 00:02:57 +02:00
|
|
|
doesn't install "multi-version" eggs is that virtualenv removes much of the need
|
|
|
|
for it.
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
pip does not have to be installed to use it, you can run ``python
|
2009-01-29 19:18:12 +01:00
|
|
|
path/to/pip.py`` and it will work. This is intended to avoid the
|
|
|
|
bootstrapping problem of installation. You can also run pip inside
|
|
|
|
any virtualenv environment, like::
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
$ virtualenv new-env/
|
|
|
|
... creates new-env/ ...
|
2008-10-16 00:24:00 +02:00
|
|
|
$ pip install -E new-env/ MyPackage
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
This is exactly equivalent to::
|
|
|
|
|
2009-01-29 19:18:12 +01:00
|
|
|
$ ./new-env/bin/python path/to/pip.py install MyPackage
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
Except, if you have ``virtualenv`` installed and the path ``new-env/``
|
|
|
|
doesn't exist, then a new virtualenv will be created.
|
2008-12-09 19:04:33 +01:00
|
|
|
|
2009-10-25 02:24:45 +01:00
|
|
|
pip also has two advanced features for working with virtualenvs -- both of
|
|
|
|
which activated by defining a variable in your environment.
|
2008-12-09 19:04:33 +01:00
|
|
|
|
2009-10-25 02:24:45 +01:00
|
|
|
To tell pip to only run if there is a virtualenv currently activated,
|
|
|
|
and to bail if not, use::
|
|
|
|
|
|
|
|
export PIP_REQUIRE_VIRTUALENV=true
|
|
|
|
|
|
|
|
To tell pip to automatically use the currently active virtualenv::
|
|
|
|
|
|
|
|
export PIP_RESPECT_VIRTUALENV=true
|
|
|
|
|
|
|
|
Providing an environment with ``-E`` will be ignored.
|
2009-05-11 18:16:22 +02:00
|
|
|
|
|
|
|
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``.
|
|
|
|
|
2009-07-28 10:11:39 +02:00
|
|
|
Do so by adding the line::
|
2009-05-11 18:16:22 +02:00
|
|
|
|
|
|
|
export PIP_VIRTUALENV_BASE=$WORKON_HOME
|
|
|
|
|
2009-07-28 10:11:39 +02:00
|
|
|
in your .bashrc under the line starting with ``export WORKON_HOME``.
|
2009-10-25 02:24:45 +01:00
|
|
|
|
|
|
|
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.
|