What a requirements.txt file does and how to use it

A requirements.txt file is a plain text list of Python packages your project needs. Instead of installing each package one at a time, you run a single command that reads the file and installs everything at once. The file contains package names, and optionally the specific versions you want.

The standard command to install from requirements.txt is pip install -r requirements.txt, run from the folder where the file sits. This works on Windows, macOS, and Linux, as long as you have pip (Python's package installer) already set up.

Requirements files are useful because they let you share your project with others, or move it between computers, without having to remember which packages you used or which versions worked together.

Key Takeaways

  • Run pip install -r requirements.txt from the command line in the folder containing the requirements.txt file.
  • The file should list one package per line, optionally with a version number like requests==2.28.0.
  • If pip is not found, you may need to use python -m pip install -r requirements.txt instead.
  • Virtual environments are recommended to keep project packages separate from your system Python.

Setting up a virtual environment first

Before installing packages, create a virtual environment — a separate folder where Python packages for this project live, isolated from your system Python. This prevents version conflicts if different projects need different versions of the same package.

On Windows, run:

python -m venv venv

On macOS or Linux, run:

python3 -m venv venv

This creates a folder called venv in your current directory. Then activate it:

Windows: venv\Scripts\activate

macOS or Linux: source venv/bin/activate

When the virtual environment is active, your command prompt will show (venv) at the start. Now any packages you install go into this folder, not your system Python.

The basic install command

Once your virtual environment is active (or if you are not using one), navigate to the folder containing requirements.txt in your command line or terminal. Then run:

pip install -r requirements.txt

The -r flag tells pip to read the file that follows. Pip will parse each line, download the specified package and version, and install it. If a package depends on other packages, pip installs those too.

Installation usually takes a few seconds to a few minutes, depending on how many packages are listed and how large they are. You will see output showing each package as it downloads and installs.

What to put in a requirements.txt file

A requirements.txt file lists packages one per line. The simplest format is just the package name:

requests flask numpy

This installs the latest version of each. If you want specific versions, use == for an exact match:

requests==2.28.0 flask==2.2.0 numpy==1.23.0

You can also use >= for "this version or newer" or ~= for "compatible versions". For example, requests>=2.25.0 installs version 2.25.0 or any newer version in the 2.x series.

To create a requirements.txt from packages already installed in your environment, run pip freeze > requirements.txt. This writes all installed packages and their exact versions to the file.

Troubleshooting common errors

If you see "pip: command not found" or "pip is not recognized", pip is not in your system path. Try python -m pip install -r requirements.txt instead. This runs pip as a Python module, which usually works even when the direct command does not.

If a package fails to install, the error message usually says why — often a missing compiler, a network issue, or an incompatible Python version. Read the error carefully; it often suggests a fix. For packages that need compilation (like numpy or scipy), you may need to install build tools first.

If you installed packages but they are not found when you run your code, make sure your virtual environment is active. Deactivate it by typing deactivate, then reactivate it with the command from the earlier section.

If requirements.txt is in a subfolder, include the path: pip install -r subfolder/requirements.txt.

Installing from requirements.txt in different environments

On a shared server or in a Docker container, the process is the same: activate the virtual environment (if one exists), navigate to the folder with requirements.txt, and run the install command. Many deployment tools (like Heroku or AWS) automatically look for requirements.txt and run the install as part of setup.

If you are working in a Jupyter notebook, you can install directly from a cell by running !pip install -r requirements.txt (the exclamation mark tells Jupyter to run a shell command). However, it is usually cleaner to install from the command line before starting the notebook.

For development work where you are adding new packages, install them with pip install packagename, then update requirements.txt by running pip freeze > requirements.txt again. This keeps the file in sync with what you actually have installed.

Frequently Asked Questions

What is the difference between requirements.txt and setup.py?

Requirements.txt lists packages your project needs to run. Setup.py is used when you are building a package to share with others — it defines metadata about your package and can list dependencies too. For most projects, requirements.txt is what you need.

Can I have multiple requirements files?

Yes. You might have requirements.txt for production packages and requirements-dev.txt for development tools. Install both by running the command twice: pip install -r requirements.txt then pip install -r requirements-dev.txt. You can also reference one file from another using -r other-file.txt as a line in the main file.

Do I need to commit the virtual environment folder to version control?

No. Commit requirements.txt instead. Add venv/ to your .gitignore file so the virtual environment folder is not tracked. Anyone who clones your project can create their own virtual environment and install from requirements.txt.

What if a package is not available on pip?

Most packages are on PyPI (the Python Package Index), which pip searches by default. If a package is not there, check the project's documentation for installation instructions. Some packages are installed from GitHub or other sources using pip install git+https://github.com/user/repo.git, which you can also put in requirements.txt.