What a requirements.txt file does and why you need it

A requirements.txt file is a plain text list of Python packages your project needs to run. Instead of installing each package one at a time by hand, you run a single command that reads the file and installs everything at once. This matters because projects often depend on dozens of packages, and keeping track of which versions work together is error-prone when done manually.

The file itself is straightforward: each line contains a package name, optionally followed by a version number. When you move your project to a different computer or share it with someone else, they can use the same requirements.txt to set up an identical environment without guessing what to install.

Key Takeaways

  • A requirements.txt file lists all the Python packages your project needs, one per line, so you can install them all at once instead of one by one.
  • You install packages from requirements.txt by running pip install -r requirements.txt in your terminal or command prompt, after activating your virtual environment.
  • Always set up a virtual environment before installing, so packages go into your project folder instead of your entire computer.
  • If you already have packages installed and want to create a requirements.txt file, run pip freeze > requirements.txt to save the list.

Setting up a virtual environment first

Before you install anything from requirements.txt, create a virtual environment — a separate folder where Python packages live for just this project. This prevents different projects from interfering with each other's packages.

Open your terminal or command prompt, navigate to your project folder, and run one of these commands depending on your operating system:

On Mac or Linux: python3 -m venv venv

On Windows: python -m venv venv

This creates a folder called venv inside your project. You only need to do this once per project.

Activating the virtual environment

After creating the virtual environment, you must set up it before installing packages. The set up command differs by operating system.

On Mac or Linux: Run source venv/bin/set up

On Windows: Run venv\Scripts\set up

When the virtual environment is active, you will see (venv) at the start of your terminal prompt. This tells you that any packages you install will go into this project's folder, not your entire computer. If you close the terminal, you will need to set up it again the next time you work on the project.

Installing packages from requirements.txt

With the virtual environment activated, run this command in your terminal:

pip install -r requirements.txt

The -r flag tells pip to read from a file instead of installing a single package. Pip will read each line of requirements.txt and install that package at the version specified. This usually takes a minute or two depending on how many packages are listed and how large they are.

If the installation succeeds, you will see a message saying "Successfully installed" followed by a list of package names. If a package fails to install, the error message will tell you why — often because the package name is misspelled, the version does not exist, or your Python version is too old or too new for that package.

Understanding what goes in requirements.txt

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

requests flask numpy

You can also specify exact versions to may support everyone uses the same code:

requests==2.31.0 flask==3.0.0 numpy==1.24.3

Or specify a minimum version if you want newer updates:

requests>=2.28.0 flask>=2.3.0

Most projects use exact versions because they have been tested together and work reliably. If you are starting a new project and do not have a requirements.txt yet, you can create one by running pip freeze > requirements.txt after installing all your packages manually. This saves the exact versions of everything you have installed.

Troubleshooting common installation problems

If you get an error that says "No module named pip", your Python installation is broken or pip is not in your system path. On Windows, try running python -m pip install -r requirements.txt instead. On Mac or Linux, try python3 -m pip install -r requirements.txt.

If you get an error about a package not being found, check the spelling in requirements.txt against the official package name on PyPI (the Python Package Index). Package names are case-sensitive and sometimes use hyphens or underscores in unexpected ways. A quick search for the package name on pypi.org will show you the correct spelling.

If installation fails because of version conflicts — one package needs an older version of something that another package needs a newer version of — you may need to adjust the versions in requirements.txt manually or contact the project maintainer. This is rare with well-maintained projects.

Frequently Asked Questions

Do I have to use a virtual environment?

Technically no, but you should. Without a virtual environment, packages install into your entire computer's Python installation, which can cause conflicts between projects and make it hard to know what each project actually needs. Virtual environments take 30 seconds to create and save hours of debugging later.

What if requirements.txt is in a subfolder?

Use the path to the file in your command: pip install -r path/to/requirements.txt on Mac or Linux, or pip install -r path\to\requirements.txt on Windows. The path can be relative to where you are in the terminal or an absolute path to the file.

Can I install from requirements.txt without activating the virtual environment?

Yes, but the packages will install into your system Python instead of your project folder. This defeats the purpose of the virtual environment. Always set up first, then install.

How do I know if a package installed correctly?

Run pip list to see all installed packages and their versions. If the package appears in the list at the version you expected, the installation worked. You can also try importing the package in Python: run python or python3, then type import packagename. If no error appears, the package is installed.

What if I need to add a new package to an existing project?

Install it normally with pip install packagename, then update requirements.txt by running pip freeze > requirements.txt again. This overwrites the old file with a new list that includes the package you just added.