How to Install requirements.txt in Python Projects
If you've ever cloned a Python project from GitHub or received someone else's code, you've almost certainly encountered a file called requirements.txt. Understanding what it does — and how to use it correctly — is one of the most practical skills in Python-based web development.
What Is requirements.txt?
A requirements.txt file is a plain text list of Python packages a project depends on. Each line typically names a package, often with a specific version number pinned to it. For example:
flask==2.3.2 requests>=2.28.0 python-dotenv==1.0.0 When you install from this file, pip (Python's package installer) reads each line and installs the listed packages into your current Python environment. It's the standard way Python developers share dependency information across machines, teams, and deployment pipelines.
The Basic Installation Command
The core command is straightforward:
pip install -r requirements.txt The -r flag tells pip to read from a file. Run this from the same directory that contains requirements.txt, or provide the full path to the file. That's the entire mechanic — but there are several variables that determine whether it runs cleanly or produces errors.
Why Virtual Environments Matter Here 🔧
Before running that command, the most important decision is where you're installing packages. Installing directly into your global Python environment works, but it creates version conflicts across projects over time.
The standard practice is to create a virtual environment first:
# Create the environment python -m venv venv # Activate it — macOS/Linux source venv/bin/activate # Activate it — Windows venvScriptsactivate Once activated, your terminal prompt usually changes to show the environment name. Then run the install:
pip install -r requirements.txt All packages install into the isolated environment, not your system Python. This is why two developers on different projects can have completely different package versions without conflict.
pip vs pip3: Which One to Use?
On systems where both Python 2 and Python 3 are installed, pip may point to the Python 2 version. If that's the case:
pip3 install -r requirements.txt Inside a virtual environment, this ambiguity largely disappears — pip and pip3 both point to the same interpreter. Outside one, it depends on how your system is configured.
Common Errors and What They Actually Mean
| Error | Likely Cause |
|---|---|
No such file or directory | Wrong working directory — requirements.txt isn't where pip is looking |
Could not find a version that satisfies the requirement | Package name is misspelled, or the pinned version no longer exists on PyPI |
Permission denied | Installing globally without admin rights — use --user flag or activate a venv |
Conflicting dependencies | Two packages in the file require incompatible versions of a shared dependency |
The --user flag installs packages into your user directory without needing system-level permissions:
pip install -r requirements.txt --user This is a reasonable fallback on managed systems where you can't create virtual environments.
Version Specifiers: What the Symbols Mean
Reading requirements.txt files is easier once you understand the version syntax:
==2.3.2— Exact version. Installs only this specific release.>=2.1— Minimum version. Installs 2.1 or anything newer.~=2.3— Compatible release. Allows patch-level updates but not major version changes.- No specifier — Latest version. pip grabs whatever is current on PyPI.
Pinned versions (==) are common in production projects to ensure consistent behavior. Looser constraints are more common in libraries that need to stay compatible across many environments.
Generating Your Own requirements.txt
If you're setting up a project for others, you generate the file with:
pip freeze > requirements.txt This captures every installed package in the active environment — including indirect dependencies. Some developers prefer using tools like pip-compile (from pip-tools) to separate direct dependencies from transitive ones, which produces cleaner, more maintainable files.
How Your Setup Affects the Outcome 🖥️
The same requirements.txt can behave very differently depending on:
- Python version — packages sometimes drop support for older Python releases
- Operating system — some packages have OS-specific builds or binary wheels (especially those with C extensions)
- Existing environment state — a dirty environment with pre-installed packages can create conflicts that a fresh virtual environment avoids
- Network access — pip pulls from PyPI by default; restricted or air-gapped environments need a local mirror or pre-downloaded wheels
- pip version — older pip versions handle dependency resolution differently; updating pip first (
pip install --upgrade pip) often resolves obscure install failures
When requirements.txt Isn't Enough
Larger or more complex projects sometimes use alternative dependency management approaches:
pyproject.tomlwith tools like Poetry or Hatch — handles both packaging and dependency locking in one placePipfile+Pipfile.lockvia Pipenv — separates dev dependencies from production ones cleanly- Conda environments (
environment.yml) — common in data science where non-Python packages (like CUDA libraries) are also dependencies
These tools often generate a requirements.txt for compatibility, but they manage complexity that a flat text file can't always handle well.
The right approach for any given project depends on its scale, who's working on it, how it's deployed, and what dependency complexity actually looks like in practice — factors that vary significantly from one setup to the next.