Hello Python

Install Python packages with pip

Many Python beginners have been confused by the various methods for installing packages. But you don’t have to be confused. Just use pip as your default and preferred method of installing and uninstalling Python packages.

Using pip is usually as easy as typing this at a command line:

pip install example
pip uninstall example

(except with the name of the package instead of example.) There are exceptions: certain packages, like NumPy, should probably just be installed from an OS package or windows EXE installer if you can’t easily get them to compile (see what pip can’t install).

If you’re convinced, you can skip the rest of this and make sure you have pip installed using this page’s section on bootstrapping pip, or use pip’s own instructions on installing pip. Otherwise, read on for more of the reasoning.

Note

The intent of this document is benign: to help beginners get comfortable installing packages, so they don’t maintain painful and harmful habits (like manually dumping files in site-packages, modifying sys.path at runtime, and reinventing wheels just to avoid managing third-party libraries). In this way, a clear, standard, general-purpose recommendation benefits both beginners and the community even if it isn’t one’s own favorite.

Why pip?

Of the available options, why choose pip? pip’s main historical competition was easy_install, which served well for quite a while but also had certain problems:

  • it could not uninstall packages.
  • it left broken packages when installations failed, causing a variety of mysterious issues.
  • its error feedback was often unhelpful.
  • it wasn’t always very actively maintained.

There were workarounds to some of these. But pip just resolved the issues. It also added a few bonus advantages of its own:

  • pip is pre-installed for you in every virtualenv. (Why should you use virtualenv?)
  • pip helps you reproduce installation of dependencies using pip freeze and pip install -r requirements.txt.
  • pip finds packages from the command line with pip search.
  • pip can install the new wheel (PEP 427) binary package format, and stays up to date with the current state of Python packaging (so you don’t really have to).

So most experienced Python developers settled on pip as a default years ago. Formalizing this, pip now also has an official recommendation (PEP 453 says: “officially recommend the use of pip as the default installer for Python packages”). For these reasons, pip is the safest and most future-proof default currently available. It not only does the job now in any case that matters, it can also be counted on to do the job for years to come. Unfortunately, this is still not clearly communicated to people who are less familiar with Python.

Despite pip’s big advantages, there are two significant issues to be aware of. The first is that pip doesn’t come with Python, which means using a less easy way to install pip itself (see Bootstrapping pip). The second is that pip can’t install every possible thing (see What pip can’t install). These issues shouldn’t be enough to make a beginner to Python avoid adopting pip as the default way to install and uninstall packages, because mitigating them is almost always easy in practice; rare corner cases and universal limitations of all Python-based installers cannot justify struggling with bad or nonexistent package management on a daily basis.

Bootstrapping pip

For historical reasons, Python doesn’t come with pip, leaving us with the annoying task of installing pip using some method less convenient than pip. That drives some people to use techniques which create much more frustration in the long run – like copying files manually into Python directories, or writing all their own libraries instead of reusing existing code. Resist these temptations, which waste way more time than they save. Once you see how to install pip, I think you’ll agree that it’s not too bad.

(This should be fixed in Python 3.4+ by PEP 453, but that’s no help for everyone who needs to use earlier versions.)

  1. Sometimes your OS ships with pip installed. Then you’re done already. To see if this is the case, try just running pip from a terminal or command line.

  2. Usually OS-specific packages for pip are available (e.g. Debian/Ubuntu python-pip, Fedora 17+ pip-python). Install one of these in the way you’re used to, and you are typically done. On Windows, try running the Windows installer for setuptools and then the Windows installer for pip. Or try installing both using pip-Win. On OS X, you can use homebrew or MacPorts to install pip.

  3. If you’re at wits’ end or just want a more foolproof solution, you should have to download and run these two Python files, in order:

In any case, don’t be scared; this usually isn’t a big deal to do, once you have this information. If one method doesn’t work, another one will. The main difficulty is sifting through lots of confusing instructions, and now you don’t have to do that.

What pip can’t install

The vast majority of Python packages can easily be installed with pip. But there are a few kinds of package which can cause problems requiring other techniques.

  • Some packages are simply broken as written, whether due to age or a mistake. Nothing can install these, the code has to be fixed. Don’t always assume that it’s pip’s fault when a package fails to install.
  • Packages with C code that you can’t easily get to compile. Find an OS package or installer, or follow provided documentation. On Linux, for example, distro package repositories provide OS-native packages for harder-to-compile libraries like numpy. On Windows, look at these prebuilt EXE installers for common Python modules. If you can’t find an installer, the project may provide documentation which you can follow to get the project built. Otherwise, that’s a bug.
  • Perhaps you are a more advanced user deploying an application, and you need to deploy precompiled binaries to speed up package installations or keep build tools off of the machines you are deploying to. pip isn’t designed for this. Check out Hynek Schlawack’s article on building your own OS-native packages. This is an app deployment strategy which uses virtualenv and pip together with OS packaging tools; you don’t have to go through this for every package you want to develop with.
  • You are trying to use an old package only distributed as an .egg file. See if it’s provided in another form, find something else to use, or if you’re really forced to, you can use easy_install for just this package.

A broken, archaic, manually intensive or poorly-documented install process tends to indicate lack of robustness in other areas as well. In the nearly-nonexistent situations where a working package simply cannot install with pip, I would recommend finding an alternative which is actively maintained.

The future for Python binary packages is wheel (accepted as a Python standard in PEP 427). pip can already install wheels, if you really need them for some reason. But if you are just starting, it is not likely you will need to use wheels, because the uses for them are somewhat specialized.

Finding Packages

Once you know how to install packages easily, you can have a lot of fun, save a lot of time, and do things better by using Python libraries that other people made (rather than reinventing every wheel). If something isn’t in the Python standard library, then search for it on PyPI or a mirror like Crate. PyPI is the main place people put Python code which they want others to use, and it is the default place that pip installs from.