|
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 |