Pip is an installer for Python packages written by Ian Bicking. It can install packages, list installed packages, upgrade packages, and uninstall packages.
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
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
On Windows, this is:
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
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
Its command-line script is installed in
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
Listing installed packages¶
To list installed packages and versions, use the
Pip will give you a listing something like this:
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'
If you want to upgrade a package to its most recent available version, use the
pip install -U Markdown
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.
Pip inside a virtualenv will only uninstall packages installed
within that virtualenv. For instance, if you try to
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
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
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¶
-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
bzr+) and end
#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
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
directory (by adding the repo directory into
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.
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
--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.