Using Python's pip to Manage Your Projects' Dependencies

Getting Started With pip

So, what exactly does pip do? pip is a package manager for Python. That means it’s a tool that allows you to install and manage libraries and dependencies that aren’t distributed as part of the standard library. The name pip was introduced by Ian Bicking in 2008:

I’ve finished renaming pyinstall to its new name: pip. The name pip is [an] acronym and declaration: pip installs packages. (Source)

Package management is so important that Python’s installers have included pip since versions 3.4 and 2.7.9, for Python 3 and Python 2, respectively. Many Python projects use pip, which makes it an essential tool for every Pythonista.

The concept of a package manager might be familiar to you if you’re coming from another programming language. JavaScript uses npm for package management, Ruby uses gem, and the .NET platform uses NuGet. In Python, pip has become the standard package manager.

Finding pip on Your System

The Python 3 installer gives you the option to install pip when installing Python on your system. In fact, the option to install pip with Python is checked by default, so pip should be ready for you to use after installing Python.

You can verify that pip is available by looking for the pip3 executable on your system. Select your operating system below and use your platform-specific command accordingly:

C:\> where pip3

On Windows and Unix systems, pip3 may be found in more than one location. This can happen when you have multiple Python versions installed. If you can’t find pip in any location on your system, then you may consider reinstalling pip.

Instead of running your system pip directly, you can also run it as a Python module. In the next section, you’ll learn how.

Running pip as a Module

When you run your system pip directly, the command itself doesn’t reveal which Python version pip belongs to. This unfortunately means that you could use pip to install a package into the site-packages of an old Python version without noticing. To prevent this from happening, you can run pip as a Python module:

$ python3 -m pip

Notice that you use python3 -m to run pip. The -m switch tells Python to run a module as an executable of the python3 interpreter. This way, you can ensure that your system default Python 3 version runs the pip command. If you want to learn more about this way of running pip, then you can read Brett Cannon’s insightful article about the advantages of using python3 -m pip.

Sometimes you may want to be more explicit and limit packages to a specific project. In situations like this, you should run pip inside a virtual environment.

Using pip in a Python Virtual Environment

To avoid installing packages directly into your system Python installation, you can use a virtual environment. A virtual environment provides an isolated Python interpreter for your project. Any packages that you use inside this environment will be independent of your system interpreter. This means that you can keep your project’s dependencies separate from other projects and the system at large.

Using pip inside a virtual environment has three main advantages. You can:

1. Be sure that you’re using the right Python version for the project at hand
2. Be confident that you’re referring to the correct pip instance when running pip or pip3
3. Use a specific package version for your project without affecting other projects

Python 3 has the built-in venv module for creating virtual environments. This module helps you create virtual environments with an isolated Python installation. Once you’ve activated the virtual environment, then you can install packages into this environment. The packages that you install into one virtual environment are isolated from all other environments on your system.

You can follow these steps to create a virtual environment and verify that you’re using the pip module inside the newly created environment:

C:\> python -m venv venv
C:\> venv\Scripts\activate.bat
(venv) C:\>  pip3 --version
pip 21.2.3 from ...\lib\site-packages\pip (python 3.10)
(venv) C:\>  pip --version
pip 21.2.3 from ...\lib\site-packages\pip (python 3.10)

Here you create a virtual environment named venv by using Python’s built-in venv module. Then you activate it with the source command. The parentheses (()) surrounding your venv name indicate that you successfully activated the virtual environment.

Finally, you check the version of the pip3 and pip executables inside your activated virtual environment. Both point to the same pip module, so once your virtual environment is activated, you can use either pip or pip3.

Reinstalling pip When Errors Occur

When you run the pip command, you may get an error in some cases. Your specific error message will depend on your operating system:

Error messages like these indicate that something went wrong with the installation of pip.

Getting errors like the ones shown above can be frustrating because pip is vital for installing and managing external packages. Some common problems with pip are related to how this tool was installed on your system.

Although the error messages for various systems differ, they all point to the same problem: Your system can’t find pip in the locations listed in your PATH variable. On Windows, PATH is part of the system variables. On macOS and Linux, PATH is part of the environment variables. You can check the contents of your PATH variable with this command:

C:\> echo %PATH%

The output of this command will show a list of locations (directories) on your disk where the operating system looks for executable programs. Depending on your system, locations can be separated by a colon (:) or a semicolon (;).

By default, the directory that contains the pip executable should be present in PATH after you install Python or create a virtual environment. However, missing pip is a common issue. Two supported methods can help you install pip again and add it to your PATH:

The ensurepip module has been part of the standard library since Python 3.4. It was added to provide a straightforward way for you to reinstall pip if, for example, you skipped it when installing Python or you uninstalled pip at some point. Select your operating system below and run ensurepip accordingly:

C:\> python -m ensurepip --upgrade

If pip isn’t installed yet, then this command installs it in your current Python environment. If you’re in an active virtual environment, then the command installs pip into that environment. Otherwise, it installs pip globally on your system. The --upgrade option ensures that the pip version is the same as the one declared in ensurepip.

Another way to fix your pip installation is to use the get-pip.py script. The get-pip.py file contains a full copy of pip as an encoded ZIP file. You can download get-pip.py directly from the PyPA bootstrap page. Once you have the script on your machine, then you run the Python script like this:

C:\> python get-pip.py

This script will install the latest version of pip, setuptools, and wheel in your current Python environment. If you only want to install pip, then you can add the --no-setuptools and --no-wheel options to your command.

If none of the methods above work, then it might be worth trying to download the latest Python version for your current platform. You can follow the Python 3 Installation & Setup Guide to make sure that pip is appropriately installed and works without errors.