3
|
1 |
Metadata-Version: 1.0
|
|
2 |
Name: pip
|
|
3 |
Version: 0.6.1
|
|
4 |
Summary: pip installs packages. Python packages. An easy_install replacement
|
|
5 |
Home-page: http://pip.openplans.org
|
|
6 |
Author: The Open Planning Project
|
|
7 |
Author-email: python-virtualenv@groups.google.com
|
|
8 |
License: MIT
|
|
9 |
Description: \
|
|
10 |
The main website for pip is `pip.openplans.org
|
|
11 |
<http://pip.openplans.org>`_. You can also install
|
|
12 |
the `in-development version <http://bitbucket.org/ianb/pip/get/tip.gz#egg=pip-dev>`_
|
|
13 |
of pip with ``easy_install pip==dev``.
|
|
14 |
|
|
15 |
|
|
16 |
Introduction
|
|
17 |
------------
|
|
18 |
|
|
19 |
pip is a replacement for `easy_install
|
|
20 |
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_. It uses mostly the
|
|
21 |
same techniques for finding packages, so packages that were made
|
|
22 |
easy_installable should be pip-installable as well.
|
|
23 |
|
|
24 |
pip is meant to improve on easy_install. Some of the improvements:
|
|
25 |
|
|
26 |
* All packages are downloaded before installation. Partially-completed
|
|
27 |
installation doesn't occur as a result.
|
|
28 |
|
|
29 |
* Care is taken to present useful output on the console.
|
|
30 |
|
|
31 |
* The reasons for actions are kept track of. For instance, if a package is
|
|
32 |
being installed, pip keeps track of why that package was required.
|
|
33 |
|
|
34 |
* Error messages should be useful.
|
|
35 |
|
|
36 |
* The code is relatively concise and cohesive, making it easier to use
|
|
37 |
programmatically.
|
|
38 |
|
|
39 |
* Packages don't have to be installed as egg archives, they can be installed
|
|
40 |
flat (while keeping the egg metadata).
|
|
41 |
|
|
42 |
* Native support for other version control systems (Git, Mercurial and Bazaar)
|
|
43 |
|
|
44 |
* Uninstallation of packages.
|
|
45 |
|
|
46 |
* Simple to define fixed sets of requirements and reliably reproduce a
|
|
47 |
set of packages.
|
|
48 |
|
|
49 |
pip is complementary with `virtualenv
|
|
50 |
<http://pypi.python.org/pypi/virtualenv>`_, and it is encouraged that you use
|
|
51 |
virtualenv to isolate your installation.
|
|
52 |
|
|
53 |
Community
|
|
54 |
---------
|
|
55 |
|
|
56 |
The homepage for pip is temporarily located `on PyPI
|
|
57 |
<http://pypi.python.org/pypi/pip>`_ -- a more proper homepage will
|
|
58 |
follow. Bugs can go on the `pip issue tracker
|
|
59 |
<http://bitbucket.org/ianb/pip/issues/>`_. Discussion should happen on the
|
|
60 |
`virtualenv email group
|
|
61 |
<http://groups.google.com/group/python-virtualenv?hl=en>`_.
|
|
62 |
|
|
63 |
Differences From easy_install
|
|
64 |
-----------------------------
|
|
65 |
|
|
66 |
pip cannot install some packages. Specifically:
|
|
67 |
|
|
68 |
* 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.)
|
|
69 |
|
|
70 |
* It doesn't understand Setuptools extras (like ``package[test]``). This should
|
|
71 |
be added eventually.
|
|
72 |
|
|
73 |
* It is incompatible with some packages that customize distutils or setuptools
|
|
74 |
in their ``setup.py`` files.
|
|
75 |
|
|
76 |
* Maybe it doesn't work on Windows. At least, the author doesn't test on
|
|
77 |
Windows often.
|
|
78 |
|
|
79 |
* It also has some extra features. Extra features the author thinks are great.
|
|
80 |
|
|
81 |
Uninstall
|
|
82 |
---------
|
|
83 |
|
|
84 |
pip is able to uninstall most installed packages with ``pip uninstall
|
|
85 |
package-name``.
|
|
86 |
|
|
87 |
Known exceptions include pure-distutils packages installed with
|
|
88 |
``python setup.py install`` (such packages leave behind no metadata allowing
|
|
89 |
determination of what files were installed), and script wrappers installed
|
|
90 |
by develop-installs (``python setup.py develop``).
|
|
91 |
|
|
92 |
pip also performs an automatic uninstall of an old version of a package
|
|
93 |
before upgrading to a newer version, so outdated files (and egg-info data)
|
|
94 |
from conflicting versions aren't left hanging around to cause trouble. The
|
|
95 |
old version of the package is automatically restored if the new version
|
|
96 |
fails to download or install.
|
|
97 |
|
|
98 |
.. _`requirements file`:
|
|
99 |
|
|
100 |
Requirements Files
|
|
101 |
------------------
|
|
102 |
|
|
103 |
When installing software, and Python packages in particular, it's common that
|
|
104 |
you get a lot of libraries installed. You just did ``easy_install MyPackage``
|
|
105 |
and you get a dozen packages. Each of these packages has its own version.
|
|
106 |
|
|
107 |
Maybe you ran that installation and it works. Great! Will it keep working?
|
|
108 |
Did you have to provide special options to get it to find everything? Did you
|
|
109 |
have to install a bunch of other optional pieces? Most of all, will you be able
|
|
110 |
to do it again?
|
|
111 |
|
|
112 |
If you've ever tried to setup an application on a new system, or with slightly
|
|
113 |
updated pieces, and had it fail, pip requirements are for you. If you
|
|
114 |
haven't had this problem then you will eventually, so pip requirements are
|
|
115 |
for you too -- requirements make explicit, repeatable installation of packages.
|
|
116 |
|
|
117 |
So what are requirements files? They are very simple: lists of packages to
|
|
118 |
install. Instead of running something like ``pip MyApp`` and getting
|
|
119 |
whatever libraries come along, you can create a requirements file something like::
|
|
120 |
|
|
121 |
MyApp
|
|
122 |
Framework==0.9.4
|
|
123 |
Library>=0.2
|
|
124 |
|
|
125 |
Then, regardless of what MyApp lists in ``setup.py``, you'll get a specific
|
|
126 |
version of Framework and at least the 0.2 version of Library. (You might think
|
|
127 |
you could list these specific versions in ``setup.py`` -- try it and you'll
|
|
128 |
quickly see why that doesn't work.) You can add optional libraries and support
|
|
129 |
tools that MyApp doesn't strictly require.
|
|
130 |
|
|
131 |
You can also include "editable" packages -- packages that are checked out from
|
|
132 |
Subversion, Git, Mercurial and Bazaar. These are just like using the ``-e``
|
|
133 |
option to pip. They look like::
|
|
134 |
|
|
135 |
-e svn+http://myrepo/svn/MyApp#egg=MyApp
|
|
136 |
|
|
137 |
You have to start the URL with ``svn+`` (``git+``, ``hg+`` or ``bzr+``), and
|
|
138 |
you have to include ``#egg=Package`` so pip knows what to expect at that URL.
|
|
139 |
You can also include ``@rev`` in the URL, e.g., ``@275`` to check out
|
|
140 |
revision 275.
|
|
141 |
|
|
142 |
Freezing Requirements
|
|
143 |
---------------------
|
|
144 |
|
|
145 |
So you have a working set of packages, and you want to be able to install them
|
|
146 |
elsewhere. `Requirements files`_ let you install exact versions, but it won't
|
|
147 |
tell you what all the exact versions are.
|
|
148 |
|
|
149 |
To create a new requirements file from a known working environment, use::
|
|
150 |
|
|
151 |
$ pip freeze > stable-req.txt
|
|
152 |
|
|
153 |
This will write a listing of *all* installed libraries to ``stable-req.txt``
|
|
154 |
with exact versions for every library. You may want to edit the file down after
|
|
155 |
generating (e.g., to eliminate unnecessary libraries), but it'll give you a
|
|
156 |
stable starting point for constructing your requirements file.
|
|
157 |
|
|
158 |
You can also give it an existing requirements file, and it will use that as a
|
|
159 |
sort of template for the new file. So if you do::
|
|
160 |
|
|
161 |
$ pip freeze -r devel-req.txt > stable-req.txt
|
|
162 |
|
|
163 |
it will keep the packages listed in ``devel-req.txt`` in order and preserve
|
|
164 |
comments.
|
|
165 |
|
|
166 |
Bundles
|
|
167 |
-------
|
|
168 |
|
|
169 |
Another way to distribute a set of libraries is a bundle format (specific to
|
|
170 |
pip). This format is not stable at this time (there simply hasn't been
|
|
171 |
any feedback, nor a great deal of thought). A bundle file contains all the
|
|
172 |
source for your package, and you can have pip install them all together.
|
|
173 |
Once you have the bundle file further network access won't be necessary. To
|
|
174 |
build a bundle file, do::
|
|
175 |
|
|
176 |
$ pip bundle MyApp.pybundle MyApp
|
|
177 |
|
|
178 |
(Using a `requirements file`_ would be wise.) Then someone else can get the
|
|
179 |
file ``MyApp.pybundle`` and run::
|
|
180 |
|
|
181 |
$ pip install MyApp.pybundle
|
|
182 |
|
|
183 |
This is *not* a binary format. This only packages source. If you have binary
|
|
184 |
packages, then the person who installs the files will have to have a compiler,
|
|
185 |
any necessary headers installed, etc. Binary packages are hard, this is
|
|
186 |
relatively easy.
|
|
187 |
|
|
188 |
Using pip with virtualenv
|
|
189 |
-------------------------
|
|
190 |
|
|
191 |
pip is most nutritious when used with `virtualenv
|
|
192 |
<http://pypi.python.org/pypi/virtualenv>`_. One of the reasons pip
|
|
193 |
doesn't install "multi-version" eggs is that virtualenv removes much of the need
|
|
194 |
for it.
|
|
195 |
|
|
196 |
pip does not have to be installed to use it, you can run ``python
|
|
197 |
path/to/pip.py`` and it will work. This is intended to avoid the
|
|
198 |
bootstrapping problem of installation. You can also run pip inside
|
|
199 |
any virtualenv environment, like::
|
|
200 |
|
|
201 |
$ virtualenv new-env/
|
|
202 |
... creates new-env/ ...
|
|
203 |
$ pip install -E new-env/ MyPackage
|
|
204 |
|
|
205 |
This is exactly equivalent to::
|
|
206 |
|
|
207 |
$ ./new-env/bin/python path/to/pip.py install MyPackage
|
|
208 |
|
|
209 |
Except, if you have ``virtualenv`` installed and the path ``new-env/``
|
|
210 |
doesn't exist, then a new virtualenv will be created.
|
|
211 |
|
|
212 |
pip also has two advanced features for working with virtualenvs -- both of
|
|
213 |
which activated by defining a variable in your environment.
|
|
214 |
|
|
215 |
To tell pip to only run if there is a virtualenv currently activated,
|
|
216 |
and to bail if not, use::
|
|
217 |
|
|
218 |
export PIP_REQUIRE_VIRTUALENV=true
|
|
219 |
|
|
220 |
To tell pip to automatically use the currently active virtualenv::
|
|
221 |
|
|
222 |
export PIP_RESPECT_VIRTUALENV=true
|
|
223 |
|
|
224 |
Providing an environment with ``-E`` will be ignored.
|
|
225 |
|
|
226 |
Using pip with virtualenvwrapper
|
|
227 |
---------------------------------
|
|
228 |
|
|
229 |
If you are using `virtualenvwrapper
|
|
230 |
<http://www.doughellmann.com/projects/virtualenvwrapper/>`_, you might
|
|
231 |
want pip to automatically create its virtualenvs in your
|
|
232 |
``$WORKON_HOME``.
|
|
233 |
|
|
234 |
You can tell pip to do so by defining ``PIP_VIRTUALENV_BASE`` in your
|
|
235 |
environment and setting it to the same value as that of
|
|
236 |
``$WORKON_HOME``.
|
|
237 |
|
|
238 |
Do so by adding the line::
|
|
239 |
|
|
240 |
export PIP_VIRTUALENV_BASE=$WORKON_HOME
|
|
241 |
|
|
242 |
in your .bashrc under the line starting with ``export WORKON_HOME``.
|
|
243 |
|
|
244 |
Using pip with buildout
|
|
245 |
-----------------------
|
|
246 |
|
|
247 |
If you are using `zc.buildout
|
|
248 |
<http://pypi.python.org/pypi/zc.buildout>`_ you should look at
|
|
249 |
`gp.recipe.pip <http://pypi.python.org/pypi/gp.recipe.pip>`_ as an
|
|
250 |
option to use pip and virtualenv in your buildouts.
|
|
251 |
|
|
252 |
Command line completion
|
|
253 |
-----------------------
|
|
254 |
|
|
255 |
pip comes with support for command line completion in bash and zsh and
|
|
256 |
allows you tab complete commands and options. To enable it you simply
|
|
257 |
need copy the required shell script to the your shell startup file
|
|
258 |
(e.g. ``.profile`` or ``.zprofile``) by running the special ``completion``
|
|
259 |
command, e.g. for bash::
|
|
260 |
|
|
261 |
$ pip completion --bash >> ~/.profile
|
|
262 |
|
|
263 |
And for zsh::
|
|
264 |
|
|
265 |
$ pip completion --zsh >> ~/.zprofile
|
|
266 |
|
|
267 |
Alternatively, you can use the result of the ``completion`` command
|
|
268 |
directly with the eval function of you shell, e.g. by adding::
|
|
269 |
|
|
270 |
eval `pip completion --bash`
|
|
271 |
|
|
272 |
to your startup file.
|
|
273 |
Keywords: easy_install distutils setuptools egg virtualenv
|
|
274 |
Platform: UNKNOWN
|
|
275 |
Classifier: Development Status :: 4 - Beta
|
|
276 |
Classifier: Intended Audience :: Developers
|
|
277 |
Classifier: License :: OSI Approved :: MIT License
|
|
278 |
Classifier: Topic :: Software Development :: Build Tools
|