Skip to main content

Pip Requirements.txt: Installing and Managing Dependencies

A requirements.txt file is the professional standard for managing Python project dependencies. It records exact package versions, enabling reproducible environments across machines and team members. Use pip freeze to generate it and pip install -r to install all dependencies in one command.

Key Takeaways​

  • pip freeze > requirements.txt generates a snapshot of all installed packages with their exact versions, capturing both direct and transitive dependencies
  • Version pinning with == ensures stability — pandas==2.1.2 guarantees that exact version, preventing breaking changes from newer releases
  • pip install -r requirements.txt installs every package at the pinned version, eliminating "works on my machine" problems and ensuring team consistency
  • Commit requirements.txt to version control (Git, etc.) — it's as critical as source code for reconstructing your project environment

What Are Dependencies and Why Do Projects Need Them?​

A dependency is an external, third-party package that your Python project relies on to function. As projects grow, they typically use multiple libraries — web frameworks like Flask or Django, data tools like pandas and NumPy, HTTP clients like requests, or API wrappers. Each installed package may itself depend on other packages, creating a chain of transitive dependencies. Manually tracking and coordinating these versions across developers and deployment environments is error-prone. The requirements.txt file solves this by documenting every dependency and its exact version, acting as a blueprint for environment reproducibility.

# Example project needs multiple external packages
import flask  # Framework for building web apps
import pandas as pd  # Data manipulation
import requests  # HTTP library for API calls
import matplotlib.pyplot as plt  # Plotting library

# Each of these has its own dependencies
# pandas depends on numpy, pytz, etc.
# matplotlib depends on numpy, pillow, etc.
# requirements.txt captures all of them

How Do You Generate a Requirements.txt File From Installed Packages?​

The pip freeze command outputs all installed packages and their versions in a format suitable for direct use with pip install. Redirect this output to a file to create your requirements.txt.

Capturing Dependencies With pip freeze​

# View all installed packages and versions
pip freeze

# Output (example):
# cycler==0.12.1
# fonttools==4.43.1
# kiwisolver==1.4.5
# matplotlib==3.8.1
# numpy==1.26.1
# pandas==2.1.2
# pillow==10.1.0
# pyparsing==3.1.1
# python-dateutil==2.8.2
# pytz==2023.3.post1
# six==1.16.0
# tzdata==2023.3

# Generate requirements.txt directly
pip freeze > requirements.txt

Understanding the output: The pip freeze command lists not only the packages you explicitly installed (like pandas and matplotlib) but also their dependencies. This completeness is critical — it ensures that when you or a teammate install from requirements.txt on another machine, every transitive dependency is present and at the correct version.

The Requirements.txt Structure​

Each line follows the format package_name==version:

pandas==2.1.2
numpy==1.26.1
matplotlib==3.8.1
requests==2.31.0
flask==3.0.0

The == operator (exact version match) is the most common specifier, ensuring absolute reproducibility. Other specifiers exist but are less common in simple projects:

# Exact version (most common for reproducibility)
pandas==2.1.2

# Greater than or equal to
pandas>=2.0.0

# Greater than or equal, less than next major
pandas>=2.1.0,<3.0.0

# Rarely used — specifies any compatible version
pandas~=2.1

What Is the Standard Workflow for Dependency Management?​

The reproducible workflow involves three steps: install packages as needed during development, freeze the exact versions, and distribute the file for team installation.

Step 1: Install Packages During Development​

As you build your project, install packages as dependencies arise:

pip install pandas
pip install matplotlib
pip install requests
pip install flask

Or install multiple at once:

pip install pandas matplotlib requests flask

Step 2: Freeze the Environment When Stable​

Once your code is tested and working, capture the environment:

pip freeze > requirements.txt

This single command records every installed package. Always commit the generated requirements.txt to your version control system:

git add requirements.txt
git commit -m "Lock dependencies for reproducibility"

Step 3: Install From Requirements.txt on New Machines​

When cloning the project on a new machine or in a CI/CD pipeline, install all dependencies in one command:

pip install -r requirements.txt

The -r flag tells pip to read package names and versions from the file and install each one at the specified version. This guarantees that all team members and production deployments use identical dependencies.

Why Is Version Pinning With == So Critical?​

Version pinning with the == operator guarantees exact version matching, preventing subtle bugs and breaking changes. When you specify pandas==2.1.2, pip installs exactly that version — not 2.1.3, not 2.2.0, not 3.0.0.

The Risk of Unpinned Versions​

Without pinning, package upgrades can break your code:

# Your code written for pandas 2.1.2
df = pd.read_csv('data.csv')
df.iteritems()  # This method exists in 2.1.2

# If pip installs pandas 3.0 (which removed iteritems()), the code breaks:
# AttributeError: 'DataFrame' object has no attribute 'iteritems'

The Guarantee of Pinned Versions​

Pinning ensures stability and reproducibility:

pandas==2.1.2  # Always version 2.1.2 — no surprises
numpy==1.26.1  # Your code expects this exact version
matplotlib==3.8.1  # Consistent across all machines

Benefits:

  • Stability: Code written today works identically six months from now
  • Reproducibility: Every team member runs the same versions
  • Debugging: You know exactly what versions caused a bug
  • Deployments: Production uses identical versions to your development environment

How Do You Update Packages When You Need a Newer Version?​

Update a single package and regenerate requirements.txt:

# Update pandas to the latest version
pip install --upgrade pandas

# Regenerate requirements.txt with the new version
pip freeze > requirements.txt

# Commit the updated file
git add requirements.txt
git commit -m "Upgrade pandas to latest version"

For controlled upgrades, use version specifiers:

# Upgrade to a specific version
pip install pandas==2.2.0

# Then regenerate
pip freeze > requirements.txt

Frequently Asked Questions​

Should you commit requirements.txt to Git?​

Yes, absolutely. Commit requirements.txt to your version control system alongside your source code. It's equally important for recreating your project. Exclude only the virtual environment directory (.venv/ or venv/) via .gitignore, not the requirements file.

What's the difference between requirements.txt and pyproject.toml?​

Modern Python projects increasingly use pyproject.toml (PEP 517/518) to specify dependencies, which is more flexible and supports semantic versioning. However, requirements.txt with pip freeze captures exact pinned versions for reproducibility. Many projects use both: pyproject.toml for ranges and requirements.txt (generated from it or pip freeze) for locked versions.

How do you handle requirements.txt in a virtual environment?​

Virtual environments isolate your project's dependencies. Always activate your project's virtual environment before running pip freeze and pip install -r:

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install packages in the venv (not system Python)
pip install pandas matplotlib

# Freeze only the venv's packages
pip freeze > requirements.txt

Without a virtual environment, pip freeze captures system-wide packages and pollutes your requirements.txt.

How do you track optional or development-only dependencies?​

Some projects need dev tools (pytest, black, flake8) only during development, not in production. Create a separate requirements-dev.txt:

# requirements.txt — production dependencies
pandas==2.1.2
flask==3.0.0

# requirements-dev.txt — development tools
pytest==7.4.0
black==23.11.0
flake8==6.1.0

Install both in development:

pip install -r requirements.txt -r requirements-dev.txt

Install only production in deployment:

pip install -r requirements.txt

Can you use comments in requirements.txt?​

Yes, lines starting with # are comments and are ignored by pip:

# Production web framework
flask==3.0.0

# Data manipulation (requires numpy internally)
pandas==2.1.2

# API communication
requests==2.31.0

Further Reading​