Install Python packages with pip¶

Introducing pip¶

Historically, many Python beginners have been confused by the various methods for installing packages, and all the arguments about them. Today, 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.

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. (OK, it’s a bit slow.)
• pip can install the new wheel (PEP 427) binary package format, and stays up to date with the current state of Python packaging.

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¶

Unfortunately, Python doesn’t come with pip. (Sometime in the future, for Python3.4+, this should be fixed by PEP 453.) For now, we have to install pip by some less convenient method than using pip. Once you see how to do it, though, it’s not so bad.

1. Sometimes your OS ships with pip installed, or someone already did it. Then you’re already done. To see if this is the case, try just running pip from a terminal or command line. If it’s not there, no harm, it was worth a try.

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.

   Using this option usually means you aren’t getting the latest version of pip, but rather whatever version your OS deemed stable; you would probably already know if this was something that should matter to you.

   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, whatever you normally would use.

3. If all else fails or you want the latest pip, the method which offers the greatest control is to download and run this file. https://raw.github.com/pypa/pip/master/contrib/get-pip.py

   Locate it on disk, change to that directory and run it with:

   python get-pip.py --user
   

   This has two really important differences from the first two methods.

   • This installs pip to a place in your user directory. Therefore it does not require sudo or admin privileges and will not interfere with system packages. On the other hand, it will not be on PATH unless you configured it that way, so typing pip might not find it. On *nix, you might have to type something like ~/.local/bin/pip until you add ~/.local/bin to your user PATH by modifying ~/.profile. On Windows, you might have to set a User Environment Variable via Control Panel.
   • The installed pip will manage packages for the python that was used to run get-pip.py. Running python get-pip.py will install a pip which looks after the packages used by python. But running python3.4 get-pip.py --user would install a pip command which looked after the packages used by that python3.4.

   I would personally not recommend sudo python get-pip.py or the equivalent, as it could mess with your system’s Python stuff and confuse you with different pip executables all over the place. But it can work OK and it’s probably your computer to mess up, right?

In any case, don’t be scared of installing pip. It’s just a matter of going down these options in order. If one method doesn’t work, another one will soon.

Installing a package for one user¶

To install a package just for yourself,

pip install --user example

The actual package files are put somewhere under your home directory, which means you don’t need special privileges like sudo, and also doesn’t interfere with system packages, but it still works mostly like you installed those packages globally.

This is especially useful if there are certain Python-based command line tools you run interactively and always want to have available, like flake8, pylint, etc. Try installing these with pip install --user instead of using OS packages; it lets you upgrade things whenever you want, the system doesn’t mess with your stuff as much and you don’t mess with the system’s stuff as much.

But if you are installing packages as dependencies of a Python project you are working on, those should normally be installed inside a virtualenv.

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 assume that it’s pip’s fault when a package fails to install.
• Some packages have 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. This is coming in the form of wheels, but it isn’t totally done yet, and maybe it isn’t what you want to use anyway. 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.
• Sometimes you have no choice but to use an old package only distributed as an .egg file. pip does not use those, only easy_install does. 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 that package.

A broken, archaic, manually intensive or poorly-documented install process tends to indicate lack of robustness in other areas as well. In the truly exceptional situations where a working package simply cannot install with pip, I would personally 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. But if you are just starting, it is not likely you will need to use wheels yet, and at this writing they still aren’t able to package binaries for Linux effectively..

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