The requirements.txt file is the standard way to specify Python package dependencies for pip. This guide covers the complete syntax with practical examples.
Basic Syntax
Simple Package Names
requests
flask
numpy
pandas
This installs the latest version of each package. Not recommended for production—always pin versions.
Pinned Versions (Recommended)
requests==2.31.0
flask==3.0.0
numpy==1.26.2
pandas==2.1.3
The == operator installs exact versions for reproducible builds.
Version Specifiers
Exact Version
package==1.2.3
Installs exactly version 1.2.3.
Minimum Version
package>=1.2.0
Installs version 1.2.0 or higher.
Maximum Version
package<=2.0.0
Installs version 2.0.0 or lower.
Version Range
package>=1.2.0,<2.0.0
Installs any version from 1.2.0 up to (but not including) 2.0.0.
Exclude Specific Version
package!=1.3.0
Installs any version except 1.3.0.
Compatible Release
package~=1.4.2
Equivalent to >=1.4.2,<1.5.0. Allows patch updates but not minor updates.
package~=1.4
Equivalent to >=1.4.0,<2.0.0. Allows minor updates but not major updates.
Wildcard
package==1.4.*
Matches any 1.4.x version.
Comments and Organization
# Core dependencies
requests==2.31.0
flask==3.0.0
# Database
sqlalchemy==2.0.23
psycopg2-binary==2.9.9 # PostgreSQL adapter
# Testing (move to dev-requirements.txt for production)
pytest==7.4.3
pytest-cov==4.1.0
Lines starting with # are comments. Inline comments work after the package spec.
Installing from Git
Default Branch
git+https://github.com/user/repo.git
Specific Branch
git+https://github.com/user/repo.git@main
git+https://github.com/user/repo.git@develop
Specific Tag
git+https://github.com/user/[email protected]
Specific Commit
git+https://github.com/user/repo.git@a1b2c3d4e5f6
SSH URLs
git+ssh://[email protected]/user/[email protected]
With Package Name
git+https://github.com/user/[email protected]#egg=package-name
Installing from URLs
Direct URL to Tarball/Zip
https://github.com/user/repo/archive/v1.0.0.tar.gz
With Package Name
https://example.com/packages/mypackage-1.0.tar.gz#egg=mypackage
Editable Installs
Editable installs (-e) link to source code so changes take effect immediately.
Local Path
-e ./my-package
-e ../shared-library
-e /absolute/path/to/package
Git Repository
-e git+https://github.com/user/repo.git#egg=package-name
-e git+https://github.com/user/repo.git@branch#egg=package-name
Extras (Optional Dependencies)
Some packages define optional dependency groups.
Install with Extras
# Install requests with security extras
requests[security]==2.31.0
# Install with multiple extras
package[extra1,extra2]==1.0.0
# Install celery with Redis support
celery[redis]==5.3.4
Common Extras Examples
# FastAPI with all optional dependencies
fastapi[all]==0.104.1
# SQLAlchemy with PostgreSQL async support
sqlalchemy[asyncio]==2.0.23
# Pandas with Excel support
pandas[excel]==2.1.3
Environment Markers
Conditionally install packages based on Python version, OS, or platform.
Python Version
# Only for Python < 3.11
tomli==2.0.1; python_version < "3.11"
# Only for Python >= 3.8
dataclasses==0.6; python_version >= "3.8"
Operating System
# Windows only
pywin32==306; sys_platform == "win32"
# Linux only
uvloop==0.19.0; sys_platform == "linux"
# macOS only
pyobjc==10.0; sys_platform == "darwin"
Platform
# 64-bit systems only
numpy==1.26.2; platform_machine == "x86_64"
Combined Markers
package==1.0.0; python_version >= "3.8" and sys_platform == "linux"
Including Other Files
Reference Another Requirements File
-r base-requirements.txt
-r dev-requirements.txt
Common Pattern
requirements.txt (production):
flask==3.0.0
gunicorn==21.2.0
sqlalchemy==2.0.23
dev-requirements.txt (development):
-r requirements.txt
pytest==7.4.3
black==23.11.0
mypy==1.7.0
Install for development:
pip install -r dev-requirements.txt
Constraints Files
Constraints files pin versions without installing packages directly.
Create constraints.txt
requests==2.31.0
urllib3==2.1.0
certifi==2023.11.17
Use Constraints
pip install -c constraints.txt package-name
Reference in Requirements
-c constraints.txt
some-package
Index URLs
Custom Package Index
--index-url https://pypi.example.com/simple/
package-name==1.0.0
Extra Index (Use Both PyPI and Custom)
--extra-index-url https://pypi.example.com/simple/
package-name==1.0.0
Trusted Host (Skip SSL)
--trusted-host pypi.example.com
--index-url http://pypi.example.com/simple/
Complete Example
# requirements.txt
# Generated: 2026-01-23
# Python: 3.11+
# Web Framework
flask==3.0.0
flask-sqlalchemy==3.1.1
flask-cors==4.0.0
# Database
sqlalchemy==2.0.23
psycopg2-binary==2.9.9; sys_platform != "win32"
psycopg2==2.9.9; sys_platform == "win32"
# HTTP Client
requests[security]==2.31.0
httpx==0.25.2
# Async Support
uvicorn[standard]==0.24.0
uvloop==0.19.0; sys_platform == "linux"
# Utilities
python-dotenv==1.0.0
pydantic==2.5.2
# Backports (Python < 3.11)
tomli==2.0.1; python_version < "3.11"
# Local package in development
-e ./shared-utils
Best Practices
- Always pin versions in production (
==not>=) - Separate dev and production requirements
- Use
pip-compilefrom pip-tools for dependency resolution - Comment sections for organization
- Generate with
pip freezebut review the output - Use hash checking for security (
--require-hashes) - Keep files sorted alphabetically within sections
- Test in clean environment before deploying
Common Commands
# Install from requirements file
pip install -r requirements.txt
# Install with upgrade
pip install -r requirements.txt --upgrade
# Generate requirements from installed packages
pip freeze > requirements.txt
# Install in editable mode
pip install -e .
# Use constraints
pip install -c constraints.txt package-name
# Show package info
pip show package-name
# Check for outdated packages
pip list --outdated