2008-10-16 00:24:00 +02:00
|
|
|
pip
|
|
|
|
===
|
2008-10-16 00:02:57 +02:00
|
|
|
|
|
|
|
.. toctree::
|
|
|
|
|
|
|
|
news
|
|
|
|
requirement-format
|
|
|
|
|
|
|
|
.. comment: split here
|
|
|
|
|
|
|
|
.. contents::
|
|
|
|
|
|
|
|
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-16 00:24:00 +02:00
|
|
|
easy_installable should be pipable 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).
|
|
|
|
|
|
|
|
* Maybe features like native support for other version control systems, or
|
|
|
|
uninstallation, will get added. (They might get added to easy_install, but I
|
2008-10-16 00:24:00 +02:00
|
|
|
think the chance for pip is higher.)
|
2008-10-16 00:02:57 +02:00
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
Also, pip will eventually be merged directly with poacheggs, making it
|
2008-10-16 00:02:57 +02:00
|
|
|
simple to define fixed sets of requirements and reliably reproduce a set of
|
|
|
|
packages.
|
|
|
|
|
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
|
|
|
|
<http://pypi.python.org/pypi/pip>`_ -- a more proper homepage
|
2008-10-16 00:02:57 +02:00
|
|
|
will follow. Bugs can go on the `poacheggs Trac instance
|
|
|
|
<http://trac.openplans.org/poacheggs/>`_ (probably that will change
|
|
|
|
too). Discussion should happen on the `virtualenv email group
|
|
|
|
<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.
|
|
|
|
|
|
|
|
.. _`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
|
|
|
|
subversion (in the future other VCS will be supported). These are just like
|
2008-10-16 00:24:00 +02:00
|
|
|
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
|
|
|
|
|
|
|
|
You have to start the URL with ``svn+`` (eventually you'll be able to use
|
2008-10-16 00:24:00 +02:00
|
|
|
``hg+`` etc), and you have to include ``#egg=Package`` so pip knows what
|
2008-10-16 00:02:57 +02:00
|
|
|
to expect at that URL. You can also include ``@rev`` in the URL, e.g., ``@275``
|
|
|
|
to check out revision 275.
|
|
|
|
|
|
|
|
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::
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
$ pip freeze -o 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::
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
$ pip freeze -o stable-req.txt -r devel-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-16 00:24:00 +02:00
|
|
|
source for your package, and you can have pip install then 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::
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
$ pip install 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
|
|
|
|
pip`` and it will work. This is intended to avoid the bootstrapping
|
|
|
|
problem of installation. You can also run pip inside any virtualenv
|
2008-10-16 00:02:57 +02:00
|
|
|
environment, like::
|
|
|
|
|
|
|
|
$ 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::
|
|
|
|
|
2008-10-16 00:24:00 +02:00
|
|
|
$ ./new-env/bin/python pip 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.
|