=== Pip === `Pip`_ is an installer for Python packages written by Ian Bicking. It can install packages, list installed packages, upgrade packages, and uninstall packages. Getting Started =============== Creating a virtualenv --------------------- We'll be using `virtualenv`_ so our installation experiments are contained and don't modify your system Python environment. If you aren't already familiar with virtualenv, you may want to read up on it first. Create a virtualenv:: virtualenv --no-site-packages pip_test_env We use the ``--no-site-packages`` flag to prevent this virtualenv from "seeing" your global Python "site-packages" directory, so that our experiments aren't confused by any Python packages you happen to already have installed globally. Recent versions of virtualenv (1.4+) automatically install pip for you inside the virtualenv (there will already be a ``pip`` script in ``pip_test_env/bin/``). If you are using a pre-1.4 virtualenv, run ``pip_test_env/bin/easy_install pip`` to install pip in the virtual environment. .. Note:: If you are using Windows, executable scripts in the virtualenv will be located at ``pip_test_env\Scripts\`` rather than ``pip_test_env/bin/``. Just replace all occurrences of the latter with the former. Let's "activate" the virtualenv to put ``pip_test_env/bin`` on our default PATH, so we can just type ``pip`` instead of ``pip_test_env/bin/pip``:: . pip_test_env/bin/activate On Windows, this is:: pip_test_env\Scripts\activate.bat In either case, your shell prompt should now begin with ``(pip_test_env)`` to remind you that a virtualenv is activated. When you are done working with this virtualenv type ``deactivate`` to remove its bin directory from your PATH. 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**')" (Because your virtualenv is activated, ``python`` runs the virtualenv's python binary in ``pip_test_env/bin/python``.) Its command-line script is installed in ``pip_test_env/bin/markdown`` (or ``pip_test_env\Scripts\markdown.bat``). The rest of Markdown's files are installed in ``pip_test_env/lib/python2.X/site-packages/markdown`` (where 2.X is your Python version), and the metadata describing what has been installed is in ``pip_test_env/lib/pythonx.x/site-packages/Markdown-2.0.3-py2.X.egg-info/``. Listing installed packages -------------------------- To list installed packages and versions, use the ``freeze`` command: pip freeze Pip will give you a listing something like this:: 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 virtualenv will only uninstall packages installed within that virtualenv. For instance, if you try to ``pip uninstall wsgiref`` it will refuse, because the virtualenv references the global Python's standard library, so the ``wsgiref`` package is not installed within the virtualenv. Installing from other sources ============================= How does pip know what to install when you run ``pip install Markdown``? By default, it checks the `Python Package Index`_ (or PyPI) for a package of that name. In this case, it found one; but what if you want to install a package that hasn't been uploaded to PyPI? You have several options: Installing from a tarball ------------------------- You can install directly from a tarball or zip file, as long as there is a working ``setup.py`` file in the root directory of the unzipped contents:: pip install path/to/mypackage.tgz You can also install from a tarball/zip file over the network:: pip install http://dist.repoze.org/PIL-1.1.6.tar.gz Installing from a VCS --------------------- Using the ``--editable`` or ``-e`` option, pip has the capability to install directly from a version control repository (it currently supports Subversion, Mercurial, Git, and Bazaar):: pip install -e svn+http://svn.colorstudy.com/INITools/trunk#egg=initools-dev This option shells out to the commandline client for each respective VCS, so you must have the VCS installed on your system. The repo URL must begin with ``svn+`` (or ``hg+``, ``git+``, or ``bzr+``) and end with ``#egg=packagename``; otherwise, pip supports the same URL formats and wire protocols supported by the VCS itself. Pip will checkout the source repo into a ``src/`` directory inside the virtualenv (i.e. ``pip_test_env/src/initools-dev``), and then run ``python setup.py develop`` in that source repo. This "links" the code directly from the repo into the virtualenv's ``site-packages`` directory (by adding the repo directory into ``easy-install.pth``), so changes you make in the source checkout are effective immediately. If you already have a local VCS checkout you want to keep using, you can just use ``pip install -e path/to/repo`` to install it "editable" in the same way. Add URLs to search for links ---------------------------- You can use the ``-f`` or ``--find-links`` option to add another URL pip should search for links to the package. If you dump some package tarballs in a webserver directory and turn on automatic indexing, you can point pip at that index page and install any of those packages, assuming you named the files in the pattern ``packagename-version.ext``. For example, if you upload a tarball ``MyApp-1.0.tgz`` to a ``my-packages`` directory on your webserver, and make sure indexing is on for that directory, you can run:: pip install MyApp -f http://www.example.com/my-packages/ Running your own package index ------------------------------ If you want more of the features provided by PyPI (including the ability to upload packages with ``python setup.py sdist upload``), you can run software such as `chishop`_, which implements the PyPI API, on your own server. Then you can use pip's ``-i`` (or ``--index-url``) or ``--extra-index-url`` options to point it at your index. For instance, if you set up your own index at http://www.example.com/chishop/, you might run:: pip install MyPrivateApp -i http://www.example.com/chishop/simple/ If you use ``-i`` pip won't check PyPI, only the index you provide. If you are installing multiple packages at once, some from your index and some from PyPI, you may want to use ``--extra-index-url`` instead, so pip will check both indexes. Requirements files ================== See `the pip documentation `_ for a good overview. .. _chishop: http://github.com/ask/chishop .. _Pip: http://pip.openplans.org/ .. _virtualenv: http://virtualenv.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/