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 depends on, along with the specific versions. Instead of installing packages one at a time by hand, you run a single command that reads the file and installs everything at once. This matters because it ensures everyone working on the same project — or you on a different machine — gets the exact same package versions, which prevents "it works on my machine" problems.
The file itself is just text. Each line names a package, optionally followed by a version number. For example, a requirements.txt might contain requests==2.28.1 or flask>=2.0.0. You create it by hand or generate it from an existing Python environment using pip freeze.
Key Takeaways
- Install all packages from requirements.txt using pip install -r requirements.txt in your terminal or command prompt.
- You must have Python and pip already installed, and you should work inside a virtual environment to avoid conflicts with other projects.
- The file format is one package per line, with optional version constraints like package==1.2.3 or package>=1.0.
- If installation fails on a specific package, the error message usually tells you what went wrong — missing system dependencies, incompatible Python version, or a typo in the package name.
Setting up a virtual environment before you install
Before running the install command, create a virtual environment — a separate Python workspace for your project. This keeps your project's packages isolated from other projects and from your system Python. On Windows, macOS, and Linux, the process is nearly identical.
Open your terminal or command prompt, navigate to your project folder, and run one of these commands depending on your Python version:
- Python 3.10 and newer: python -m venv venv
- Python 3.9 and older: python3 -m venv venv
This creates a folder called venv in your project. Next, activate it. On Windows, run venv\Scripts\activate. On macOS or Linux, run source venv/bin/activate. Your terminal prompt should change to show (venv) at the start, confirming the environment is active.
Running the install command
With your virtual environment active, run this command in the same folder where your requirements.txt file sits:
pip install -r requirements.txt
The -r flag tells pip to read from a file. Pip will parse each line, download the specified version of each package, and install it. On a typical project with 10 to 20 packages, this takes 30 seconds to a few minutes depending on package size and your internet speed.
If you want to see what pip is doing in detail, add the -v flag: pip install -r requirements.txt -v. This prints every step, which helps when troubleshooting.
Understanding version constraints in the file
Requirements.txt supports several ways to specify versions. The most common are:
| Format | Meaning | Example |
|---|---|---|
| package==1.2.3 | Install exactly this version | requests==2.28.1 |
| package>=1.0 | Install this version or any newer one | flask>=2.0.0 |
| package>=1.0,<2.0 | Install within a range | django>=3.0,<4.0 |
| package | Install the latest available version | numpy |
Most projects use == to lock exact versions, because it guarantees reproducibility. If a package author releases a new version with a breaking change, your code won't break unexpectedly. When you want to update packages later, you edit the file or regenerate it with pip freeze > requirements.txt.
Troubleshooting common installation errors
If a package fails to install, pip prints an error message. The most common causes are a typo in the package name, an incompatible Python version, or a missing system dependency.
Package not found: If you see "No matching distribution found", check the spelling. Package names on PyPI (the official Python package repository) are case-insensitive but often use hyphens instead of underscores. For example, the package is pillow, not PIL. Search PyPI.org to confirm the exact name.
Python version mismatch: Some packages require a specific Python version. If the error mentions "python_requires", check what version the package needs and whether your Python installation meets it. Run python --version to see what you have.
System dependencies: A few packages (like psycopg2 for PostgreSQL or mysqlclient for MySQL) need system libraries installed first. The error message usually hints at what's missing. On Ubuntu or Debian, you might need to run apt-get install for a C compiler or database client library. On macOS with Homebrew, use brew install. On Windows, the package often includes pre-built binaries, so this is less common.
Verifying the installation worked
After pip finishes, verify that packages installed correctly by running pip list. This prints every installed package and its version. Scan the output to confirm the packages from your requirements.txt are there with the right versions.
You can also test by importing a package in Python. Run python to start the Python interpreter, then type import package_name. If it imports without error, the package is installed. Type exit() to leave the interpreter.
Frequently Asked Questions
Do I have to use a virtual environment?
Technically no, but you should. Without one, packages install into your system Python, which can conflict with other projects or system tools. Virtual environments take 10 seconds to create and save hours of debugging later.
What if requirements.txt is in a subfolder?
Specify the path: pip install -r path/to/requirements.txt. On Windows, use backslashes: pip install -r path\to\requirements.txt. Or navigate to that folder first and use pip install -r requirements.txt.
Can I install from multiple requirements files?
Yes. Run pip install -r requirements1.txt -r requirements2.txt. This is useful when you have base requirements and environment-specific ones (like separate files for development and production).
What does "already satisfied" mean in the output?
It means that version of the package is already installed in your virtual environment, so pip skips it. This is normal and not an error. If you want to reinstall anyway, use pip install -r requirements.txt --force-reinstall.