What pip install does and when you need it

pip install is the command you type into your terminal to download and set up Python packages — libraries of code that other people wrote that you want to use in your own projects. When you run pip install package-name, pip finds that package online, downloads it, and puts it in a location where Python can find it. Without it, you would have to write everything from scratch.

You need pip install whenever you want to use a package that did not come built into Python. If you are following a tutorial that says "install requests" or "install Django", that is pip install in action. Most Python projects rely on at least a few outside packages, so this is one of the first things you will do as a Python user.

Key Takeaways

  • The basic command is pip install package-name, typed into your terminal or command prompt, and it downloads and sets up the package for you.
  • You need to have Python and pip already installed on your computer before you can use pip install — check by typing pip --version in your terminal.
  • If pip install fails, the most common reason is that you are using the wrong pip version (Python 2 vs Python 3) or you are in the wrong folder.
  • Virtual environments let you keep different projects' packages separate so they do not interfere with each other.
  • You can install a specific version of a package by typing pip install package-name==1.2.3 instead of just the package name.

Check that pip is installed and working

Before you run pip install, confirm that pip exists on your computer and is connected to the right version of Python. Open your terminal (on Mac or Linux) or command prompt (on Windows) and type this:

pip --version

If you see a version number and a Python version number, pip is installed. If you see "command not found" or "pip is not recognized", pip is either not installed or your computer cannot find it. On Windows, you may need to use py -m pip --version instead. On Mac or Linux, you may need to use pip3 --version if you have both Python 2 and Python 3 installed — use whichever one matches the Python version you want to work with.

Run your first pip install command

Once you have confirmed pip works, navigate to the folder where your Python project lives. Open your terminal or command prompt, use cd to move into that folder, and then type the install command. Here is an example that installs a package called requests, which is used for downloading web pages:

pip install requests

Press Enter and wait. pip will download the package and any other packages it needs to work. You will see text scrolling past as it works. When it finishes, you will see a line that says "Successfully installed" followed by the package name. You can now use that package in your Python code by typing import requests at the top of your script.

If you see an error message, the most common causes are: you typed the package name wrong, the package does not exist on PyPI (the official Python package repository), or you are using the wrong pip version. Double-check the package name on the project's documentation or on pypi.org.

Install a specific version of a package

Sometimes you need a particular version of a package because your code was written for that version, or because a newer version broke something. Instead of just the package name, type the package name, two equals signs, and the version number:

pip install requests==2.28.0

This installs version 2.28.0 of requests instead of the newest version. You can find the version numbers available for any package on pypi.org — search for the package name and look at the "Release history" section.

You can also install the newest version that is at least a certain version number by using pip install requests>=2.28.0, or the newest version that is older than a certain number by using pip install requests<3.0.0. This is useful when you know your code works with a range of versions but not all of them.

Use virtual environments to keep packages separate

If you work on multiple Python projects, you will eventually run into a problem: Project A needs version 1.0 of a package, but Project B needs version 2.0 of the same package. If you install both versions globally (in the main Python installation), they will conflict. A virtual environment is a separate folder that holds its own copy of Python and its own set of packages, so each project can have exactly what it needs.

To create a virtual environment, navigate to your project folder and type:

python -m venv env

This creates a folder called env that holds the virtual environment. Then activate it by typing one of these commands, depending on your operating system:

On Mac or Linux: source env/bin/activate

On Windows: env\Scripts\activate

When the virtual environment is active, you will see (env) at the start of your terminal prompt. Now when you run pip install, the packages go into this virtual environment instead of your main Python installation. Each project gets its own virtual environment, so they never interfere with each other. When you are done working on the project, type deactivate to turn off the virtual environment.

Install multiple packages at once

If a project needs many packages, typing pip install over and over is tedious. Instead, create a text file called requirements.txt in your project folder and list the packages you need, one per line. You can include version numbers if you want:

requests==2.28.0 flask==2.2.0 numpy>=1.20.0

Then install everything in that file at once by typing:

pip install -r requirements.txt

This is the standard way Python projects share their dependencies. When someone gives you a project and a requirements.txt file, this is how you set it up on your computer. You can also create a requirements.txt from packages you have already installed by typing pip freeze > requirements.txt, which is useful when you want to save the exact state of your project so someone else can reproduce it.

Troubleshoot common pip install errors

If pip install fails, check these things in order. First, make sure you are using the right pip version. If you have both Python 2 and Python 3 installed, pip might point to Python 2 and you might need to use pip3 instead. Type pip --version to see which Python version it is connected to. Second, make sure you are in the right folder — your terminal should be inside your project folder when you run the command. Third, double-check that you typed the package name correctly by looking it up on pypi.org.

If you see a permission error on Mac or Linux, do not use sudo to force the install. Instead, use a virtual environment (see the section above). If you see a message about a compiler or build tools missing, the package needs to be compiled from source code on your computer, which requires extra software. The error message usually tells you what to install — follow those instructions, then try pip install again.

If pip install says the package does not exist, the package name might be different from what you expected. Search pypi.org for the package to find the exact name. Some packages have hyphens in their names on the website but underscores when you install them, or vice versa.

Frequently Asked Questions

What is the difference between pip and pip3?

pip usually points to Python 2, and pip3 points to Python 3. Since Python 2 is no longer supported, you should use pip3 unless you have a specific reason to use Python 2. Check which one you have by typing pip --version and pip3 --version and seeing which Python version each one shows.

Can I install a package from somewhere other than PyPI?

Yes. You can install from a GitHub repository by typing pip install git+https://github.com/username/repo.git, or from a local folder by typing pip install /path/to/folder. Most of the time you will install from PyPI, but this is useful when you are working with code that has not been published yet or when you need a version that is not on PyPI.

Do I need to install packages every time I start a new project?

Yes, but only once per project. When you create a new virtual environment for a project, you run pip install to set up that environment. After that, as long as you activate the virtual environment before working on the project, the packages stay installed. If you close your terminal and come back later, you just activate the virtual environment again — you do not reinstall the packages.

What does it mean when pip says a package is already satisfied?

It means the package is already installed in your current environment, so pip does not need to download it again. If you are trying to update to a newer version, use pip install --upgrade package-name or pip install -U package-name instead.

How do I uninstall a package?

Type pip uninstall package-name and answer yes when pip asks for confirmation. If you want to uninstall everything in a requirements.txt file, type pip uninstall -r requirements.txt.