pip install requirements.txt is one of the most common Python commands for installing dependencies. However, many developers misuse it by generating requirements files with pip freeze, which can lead to bloated environments and dependency conflicts.
In this post, we’ll break down what this command actually does, why the typical usage is often flawed, and how to adopt a cleaner workflow using pip-tools.
What does pip install -r requirements.txt do?
The -r flag in pip tells it to read a file — typically called requirements.txt — and install all the packages listed in that file.
Example:
Django==4.2.3
requests>=2.25.0
uvicorn
Running:
pip install -r requirements.txt
will install Django version 4.2.3, any version of requests greater than or equal to 2.25.0, and the latest available version of uvicorn.
Sounds simple. But there’s a catch — where that file came from matters a lot.
The common mistake: Freezing the whole environment
A typical mistake is to generate the requirements file like this:
pip freeze > requirements.txt
While it works, it dumps every installed package in your virtual environment, including transitive dependencies that were installed automatically. This leads to a bloated file that looks like:
certifi==2023.7.22
charset-normalizer==3.3.2
idna==3.4
You didn’t install those directly, but now they’re locked in your project.
This makes version upgrades harder, increases the risk of conflicts, and creates noise in your Git history every time a small version bump occurs.
Common errors when running pip install -r requirements.txt
If you’ve tried to install from a requirements.txt file and hit errors, you’re not alone. Here are the most frequent ones — and how to fix them:
FileNotFoundError
FileNotFoundError: [Errno 2] No such file or directory: 'requirements.txt'
What does it mean:
Pip can’t find the file — either it’s missing or you’re in the wrong directory.
Fix:
- Ensure requirements.txt exists in the current folder.
- Or use the full path:
pip install -r ./requirements.txt
Could not find a version that satisfies the requirement
Could not find a version that satisfies the requirement somepackage==99.99.99
What does it mean:
You’ve pinned a version that either doesn’t exist or is incompatible.
Fix:
- Double-check the version on PyPI.
- Try relaxing the constraint (e.g. somepackage>=1.0).
- Use a dependency resolver like pip-tools to handle versioning for you.
SSL error or timeout
SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
What does it mean:
This often points to network issues or outdated pip or cert packages.
Fix:
- Ensure you’re online.
- Upgrade pip and setuptools:
pip install --upgrade pip setuptools
Dependency conflicts
ERROR: Cannot install X and Y because these packages have conflicting dependencies
What does it mean:
Two packages require incompatible versions of the same dependency.
Fix:
- Use pip-compile (from pip-tools) to automatically resolve and pin compatible versions.
- Avoid manually editing a frozen requirements file.
Better alternative: Use pip-tools
Instead of editing requirements.txt by hand or freezing the entire environment, consider using pip-tools. It introduces a cleaner, two-file approach:
- requirements.in — where you list only your direct dependencies
- requirements.txt — a compiled file with locked versions and hashes
Step 1: Install pip-tools
pip install pip-tools
Step 2: Create the requirements.in
fastapi
uvicorn
Step 3: Compile the dependencies
pip-compile requirements.in
This generates a requirements.txt that looks like this:
fastapi==0.110.0
# via -r requirements.in
pydantic==2.6.4
# via fastapi
starlette==0.37.2
# via fastapi
uvicorn==0.29.0
# via -r requirements.in
Step 4: Install
pip install -r requirements.txt
Or, to exactly sync your environment:
pip-sync
Summary: Install python requirements the right way
The pip install -r requirements.txt command is essential for managing Python dependencies, but how you generate and maintain that file matters.
Avoid:
- Freezing your whole environment
- Locking transitive dependencies
- Editing version numbers manually
Instead:
- Use requirements.in to list what you actually care about
- Use pip-compile to generate the full, safe, reproducible list
- Use pip-sync to install exactly what your app needs
This small change can save hours of debugging and make your Python projects far more reliable, especially in production environments or cloud platforms like seenode.