So You Want to Install a Python Package

January 6, 2011 ⋅ 1 Comment »

As a Python developer, sooner or later you’ll want to install a package from the Python Package Index. Unfortunately, this is not as simple as it could be. Most documentation tells you to use easy_install, but maybe you’ve heard that all the cool kids are using pip these days. What’s the difference, anyhow? The goal of this article is to clear up some of this confusion, and to provide a clear and simple recommendation of how to install Python packages.

Here’s the short version: use pip install SomePackage instead of easy_install SomePackage. Pip is mostly better than easy_install, but since pip depends on setuptools, you can always use easy_install if you need to. In fact, the simplest way to install pip is easy_install pip.

If you’re not a Python developer, and just want to install a couple packages and get on with your life, you may want to jump ahead to the installation instructions.

The Problem, and a Little History

The most basic way to install a package is to download the source code and run python setup.py install inside the package directory. You don’t need any special tools to do this — it requires only the distutils module, which is included in the standard library. This works fine, but as a package management solution, it leaves a little to be desired:

• there’s no way to install several versions of the same package
• you have to manually download all the dependencies, and install them in the right order
• there’s no easy way to uninstall packages

Setuptools and easy_install were created to solve these problems. Setuptools is a package that (among other things) allows Python to understand .egg files, an archive format for Python packages. easy_install is a script for downloading and installing a package and all its dependencies.

Now, it turns out that setuptools and easy_install introduce a few problems of their own. The problems with setuptools are beyond the scope of this article, but you don’t really need to worry about it if you’re just trying to install a package. The problems with easy_install are probably best summarized by the pip documentation:

pip is meant to improve on easy_install. Some of the improvements:

• 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 being installed, pip keeps track of why that package was required.
• 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).
• Native support for other version control systems (Git, Mercurial and Bazaar)
• Uninstallation of packages.
• Simple to define fixed sets of requirements and reliably reproduce a set of packages.

Installing Pip

Okay, now that you know why you should use pip instead of easy_install, how should you install pip? Well, that depends. There’s a simple way, and there’s a better way. If you’re a Python developer, or you don’t have root/administrative access to your computer, you should use The Better Way. If not, you may want to use The Simple Way.

The Simple Way

Since pip depends on setuptools, you’ll need to install that first. I’ve written a small (experimental) script to make this easier — just download getpip.py and run it in the Python interpreter. (On Mac OS or Linux, you may need to run it as ‘sudo python getpip.py’.) This will install (or upgrade) setuptools, then use easy_install to install pip.

When that’s done, you can verify that pip is installed by running:

pip help

If it works, you’re done. Wasn’t that easy?

If it didn’t work, you should try installing setuptools by following the detailed installation instructions. Once you’ve got setuptools installed, you can install pip using easy_install pip (or sudo easy_install pip, if you’re on Mac OS or Linux).

If the installation failed because you don’t have root/administrative access to your computer, you should try The Better Way.

The Better Way: Virtualenv

If you’re a Python developer, I highly recommend that you start using virtualenv, if you don’t already. Virtualenv allows you to create local, isolated Python environments, each with a different set of installed packages. As a bonus, virtualenv installs pip into each new environment that you create, so you don’t even need to install pip globally.

You don’t even need to install virtualenv, just grab the latest version of virtualenv.py. Here’s the setup that I recommend:

1. Use virtualenv to create a base Python environment for your user account:

   python virtualenv.py ~/venv/base

2. Make this environment your default Python environment by adding the following line to the bottom of your ~/.profile or ~/.bash_profile file:

   source ~/venv/base/bin/activate

   You can test that it’s working by opening a new terminal window and checking that which python returns something like ~/venv/base/bin/python.

3. Fearlessly install new packages using pip!

   Virtualenv helpfully installs pip into each virtual environment it creates. When you use this version of pip, you won’t affect the system-wide installation of Python, only your local one in ~/venv/base.

Further Reading

You can learn more about pip from the documentation. If you’re a Python developer and interested in the future of Python packaging, you should take a look at The Hitchhiker’s Guide to Packaging and the Python distutils-sig mailing list.