What requirements.txt does and how to use it

A requirements.txt file is a plain text list of Python packages your project needs to run. Instead of installing each package one by one, you can install them all at once by pointing your package manager to this file. The file contains package names and often the specific versions you want — for example, requests==2.28.1 or flask>=2.0.

The most common way to install from requirements.txt is with pip, Python's default package manager. The command is straightforward: pip install -r requirements.txt. The -r flag tells pip to read the file and install everything listed inside it.

This approach saves time when you're setting up a project on a new machine, sharing code with teammates, or deploying to a server. Instead of asking "what packages do I need?", you have one file that answers it.

Key Takeaways

  • Install all packages from requirements.txt at once by running pip install -r requirements.txt in the directory where the file is located.
  • The file must be named exactly requirements.txt (or you can specify a different name with the -r flag, like pip install -r dev-requirements.txt).
  • Make sure you are using the correct Python environment — if you have multiple Python versions installed, use pip3 install -r requirements.txt to ensure you are using Python 3.
  • You can create your own requirements.txt by running pip freeze > requirements.txt in an active virtual environment, which lists all currently installed packages.

Before you install: check your Python environment

Before running the install command, confirm you are in the right place and using the right Python version. Open your terminal or command prompt and navigate to the folder containing requirements.txt. You can check which Python version you have by typing python --version or python3 --version.

If you see Python 2, use pip3 instead of pip in all commands. Python 2 is no longer supported, and many modern packages require Python 3. If you do not have Python installed at all, download it from python.org and run the installer.

It is also worth checking whether you are inside a virtual environment. If you are, you will usually see the environment name in parentheses at the start of your terminal prompt, like (myenv). Using a virtual environment keeps your project's packages separate from your system Python, which prevents conflicts. If you are not in one and the project has a virtual environment folder (often called venv, env, or .venv), activate it first.

The basic install command and what happens

Once you are in the right directory and environment, run pip install -r requirements.txt. Pip will read the file line by line, download each package from PyPI (the Python Package Index), and install it on your machine.

The output will show each package as it installs, along with its version number. If a package depends on other packages, pip installs those too automatically. The process usually takes a few seconds to a few minutes, depending on how many packages you have and your internet speed.

When it finishes, you will see a message like "Successfully installed [package names]" or "Requirement already satisfied" if some packages were already there. At that point, your project has everything it needs to run.

Handling version conflicts and installation errors

Sometimes pip cannot install a package because the version you specified does not exist, or because it conflicts with another package already on your system. The error message will tell you what went wrong — for example, "ERROR: Could not find a version that satisfies the requirement".

If a specific version is not available, check the requirements.txt file and update that line to a version that exists. You can search PyPI.org to see what versions are actually released. If two packages conflict with each other (one needs version 1.0 of a dependency, the other needs version 2.0), you may need to update one of the packages in requirements.txt to a newer version that works with the other.

If you are installing into a system Python (not a virtual environment) and get a permission error, try pip install --user -r requirements.txt instead. This installs packages just for your user account rather than system-wide. On Linux or Mac, you can also use sudo, but this is less safe because it installs packages with root privileges.

Creating your own requirements.txt file

If you are starting a new project and want to create a requirements.txt file, the easiest way is to use pip freeze. First, set up a virtual environment and install the packages your project needs. Then run pip freeze > requirements.txt. This command captures every package currently installed in that environment and writes it to a file with exact version numbers.

The resulting file will look something like this:

requests==2.28.1 flask==2.2.2 python-dotenv==0.20.0

You can edit this file by hand if you want to loosen version constraints. For example, change requests==2.28.1 to requests>=2.28.0 to allow newer patch versions, or requests~=2.28 to allow newer minor versions but not major ones. This gives other developers or your future self some flexibility when they install the packages.

Using requirements.txt with different package managers

Pip is the standard, but other Python package managers can also read requirements.txt. Poetry and Pipenv are two alternatives that some projects use instead of pip. If your project uses Poetry, you would run poetry install instead, and Poetry reads from a pyproject.toml file rather than requirements.txt (though Poetry can import from requirements.txt if you ask it to). If your project uses Pipenv, you would run pipenv install, which reads from a Pipfile.

Most projects you encounter will use pip and requirements.txt, so that is the safest assumption. If you are unsure which one a project uses, look in the project folder for a pyproject.toml file (Poetry), a Pipfile (Pipenv), or a setup.py file (older pip-based projects). The presence of one of these files tells you which tool to use.

Frequently Asked Questions

What if requirements.txt is in a different folder than where I am running the command?

You can specify the full path to the file. For example, if requirements.txt is in a subfolder called config, run pip install -r config/requirements.txt. On Windows, use backslashes: pip install -r config\requirements.txt. You can also navigate to the folder containing requirements.txt first using cd, then run the command without a path.

Can I install from multiple requirements files at once?

Yes. Run pip install -r requirements.txt -r dev-requirements.txt to install from both files. This is useful when you have a base set of packages everyone needs and a separate set for development (like testing tools). Pip will install all packages from both files.

How do I know if the installation worked?

After installation finishes, run pip list to see all installed packages and their versions. You can also try importing one of the packages in Python: open a Python shell by typing python, then type import packagename. If there is no error, the package installed correctly.

What does the -r flag actually mean?

The -r flag stands for "requirements" and tells pip to read package names from a file instead of from the command line. Without it, pip would treat requirements.txt as a package name and try to download a package called "requirements.txt", which does not exist.

Can I update all packages in requirements.txt to their latest versions?

Pip does not have a built-in command for this, but you can use a tool like pip-upgrade or manually edit the version numbers in requirements.txt. A safer approach is to update one package at a time by running pip install --upgrade packagename, then running pip freeze > requirements.txt again to capture the new versions.