What a requirements.txt file does and how to install from it

A requirements.txt file is a text document that lists all the Python packages your project needs, along with their version numbers. Instead of installing packages one at a time, you can install everything at once by pointing pip (Python's package installer) to this file. The command is simple: pip install -r requirements.txt — the -r flag tells pip to read the file and install each package listed inside.

This approach saves time when you're setting up a project on a new machine, sharing code with teammates, or deploying to a server. Everyone working on the same project gets the exact same package versions, which prevents the "it works on my machine" problem.

Key Takeaways

  • Run pip install -r requirements.txt from the same folder where the requirements.txt file is located, or provide the full path to the file.
  • The file must be a plain text document with one package per line, formatted as package_name==version_number or just package_name if you don't care about the version.
  • Use a virtual environment before installing to keep your project's packages separate from your system Python installation.
  • If installation fails, check that pip is up to date by running pip install --upgrade pip first.

Setting up a virtual environment before you install

Before installing packages from requirements.txt, create a virtual environment — a separate Python workspace for your project. This keeps your project's packages from interfering with other Python projects on your machine. On Windows, macOS, or Linux, the process is nearly identical.

Open your terminal or command prompt, navigate to your project folder, and run python -m venv venv. This creates a folder called venv that holds your isolated Python setup. Then activate it: on Windows, run venv\Scripts\activate; on macOS or Linux, run source venv/bin/activate. Your terminal prompt will change to show the virtual environment name in parentheses, like (venv).

Once activated, any packages you install go into this virtual environment only. When you're done working, type deactivate to exit the virtual environment.

The correct command and where to run it

With your virtual environment activated, run pip install -r requirements.txt from the command line. You must be in the same folder as the requirements.txt file, or you need to provide the path to it. For example, if requirements.txt is in a subfolder called config, you would run pip install -r config/requirements.txt.

Pip will read the file line by line and download each package from the Python Package Index (PyPI). The installation can take anywhere from a few seconds to several minutes depending on how many packages are listed and how large they are. Your terminal will show progress as each package installs.

What format the requirements.txt file must follow

The requirements.txt file is plain text with one package per line. The simplest format is just the package name: requests or numpy. If you want to lock in a specific version, use two equals signs: requests==2.31.0 or numpy==1.24.3. You can also use comparison operators like requests>=2.25.0 (version 2.25.0 or newer) or requests<3.0 (any version before 3.0).

Blank lines and comments (lines starting with #) are ignored, so you can organize the file however you want. Many developers group related packages together with comments above them, like # Web framework before Flask or Django entries.

If you already have a project with packages installed and want to create a requirements.txt file, run pip freeze > requirements.txt. This command writes out all currently installed packages with their exact versions into a new file.

Troubleshooting when installation fails

If pip says it cannot find a package, first check that the package name is spelled correctly in requirements.txt. Package names on PyPI are case-insensitive but sometimes use hyphens instead of underscores — for example, Pillow not PIL, and pyyaml not yaml.

If you get a permission error on macOS or Linux, do not use sudo with pip. Instead, make sure you are inside a virtual environment. If you are using the system Python without a virtual environment, that is the root cause. Create a virtual environment and try again.

If pip itself is outdated, it may fail to install newer packages. Run pip install --upgrade pip to update pip first, then try installing from requirements.txt again. On Windows, this command is python -m pip install --upgrade pip.

Installing only part of a requirements file

If you have a large requirements.txt and want to install only certain packages, you can edit the file temporarily to comment out the ones you do not need. Add a # at the start of any line you want to skip, then run the install command as usual.

Alternatively, you can install individual packages from the command line without using the file: pip install package_name==version_number. This is useful for testing a single package before committing it to requirements.txt.

Frequently Asked Questions

Do I have to use a virtual environment?

No, but it is strongly recommended. Without a virtual environment, packages install into your system Python, which can cause conflicts between projects and make it harder to share your code with others. A virtual environment takes 30 seconds to create and prevents these problems.

What if the requirements.txt file has a package I do not want?

Edit the file and delete or comment out that line (add a # at the start), then run the install command again. Pip will skip commented lines and only install what remains.

Can I install from a requirements file with a different name?

Yes. The -r flag works with any filename. For example, pip install -r dev-requirements.txt or pip install -r requirements-production.txt. Many projects use multiple requirements files for different environments.

How do I know if installation worked?

Run pip list to see all installed packages. You should see the packages from your requirements.txt file in the output. You can also try importing a package in Python: open a Python shell with python and type import package_name — if it works without an error, the package is installed.

What if I need to update a package version later?

Edit the version number in requirements.txt and run pip install -r requirements.txt --upgrade. The --upgrade flag tells pip to replace older versions with the new ones you specified.