requirements.txt

A plain-text file format for declaring Python package dependencies. Each line specifies a package and optional version constraint. The file is consumed by pip, uv, and other installers, typically via pip install -r requirements.txt. The filename is a convention, not a requirement — any text file works.

Syntax

Each non-blank, non-comment line is a requirement specifier. Comments begin with #.

# Pin to an exact version
numpy==1.24.1

# Set a minimum version
requests>=2.28.0

# Compatible release (>=2.0, <3.0)
pandas~=2.0

# No version constraint
flask

# Environment markers
pywin32; sys_platform == 'win32'

The format also supports options that control installer behavior:

# Include dependencies from another file
-r base-requirements.txt

# Install a local package in editable mode
-e .

# Use a custom package index
--index-url https://pypi.example.com/simple/

Common Patterns

A hand-written requirements.txt declares direct dependencies with flexible version ranges:

# requirements.txt
requests>=2.28
pandas~=2.0
sqlalchemy>=2.0,<3.0

A pinned requirements.txt (generated by pip freeze, pip-tools, or uv) locks every package — including transitive dependencies — to exact versions:

# requirements.txt (pinned)
certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.7
numpy==1.26.4
pandas==2.2.1
python-dateutil==2.9.0
pytz==2024.1
requests==2.31.0
six==1.16.0
sqlalchemy==2.0.29
tzdata==2024.1
urllib3==2.2.1

The hand-written file is easier to maintain. The pinned file produces reproducible installs. Most workflows use both: a loose file for authoring and a pinned file for deployment.

Limitations

• No Python version specification. The file cannot declare which Python versions the project supports; that metadata belongs in pyproject.toml.
• No dependency groups. There is no built-in mechanism to separate production from development dependencies. The common workaround is maintaining multiple files (requirements.txt, requirements-dev.txt), which adds overhead.
• Not reproducible by default. Without pinning every transitive dependency, installs can differ between machines and over time. Tools like pip-tools and uv solve this by generating fully pinned output.
• No project metadata. The file carries no information about the project itself — no name, version, or description. It is a dependency list, not a project definition.
• Being superseded. PEP 621 established pyproject.toml as the standard place to declare dependencies alongside project metadata. Most modern tools support it natively.

Learn More

• requirements.txt file format documentation
• Install packages in a virtual environment using pip and venv