requirements.txt Cheatsheet
requirements.txt is pip’s plain-text dependency list format — no formal spec, but a well-established convention pip itself defines and parses.
Basic Syntax
# Comments start with a hash
requests
pandas
numpy==1.26.4
Version Specifiers
requests # any version (unpinned — risky for reproducibility)
requests==2.31.0 # exact version
requests>=2.31.0 # minimum version
requests>2.31.0 # strictly greater than
requests<=2.31.0 # maximum version
requests<2.31.0 # strictly less than
requests!=2.30.0 # exclude a specific version
requests>=2.28,<3.0 # version range
requests~=2.31.0 # compatible release: >=2.31.0, <2.32.0 (locks the minor version)
requests~=2.31 # compatible release: >=2.31, <3.0 (locks the major version)
~= (compatible release) is the most common choice for applications — it allows patch-level updates (bug fixes) but blocks anything that might introduce breaking changes.
Extras
requests[socks] # install with an optional extra/feature set
uvicorn[standard]==0.30.0
pandas[excel,parquet]
Environment Markers (conditional installs)
pywin32; platform_system == "Windows"
uvloop; platform_system != "Windows"
dataclasses; python_version < "3.7"
importlib-metadata; python_version < "3.8"
requests==2.31.0; python_version >= "3.8" and python_version < "3.13"
Available markers: python_version, python_full_version, os_name, sys_platform, platform_system, platform_machine, implementation_name.
Installing From Other Sources
# Git repositories
git+https://github.com/user/repo.git
git+https://github.com/user/repo.git@branch_name
git+https://github.com/user/repo.git@v1.2.0 # specific tag
git+https://github.com/user/repo.git@abc1234 # specific commit hash
git+https://github.com/user/repo.git#egg=mypackage # explicit package name hint
# Local paths
./local-package/ # editable-friendly local directory
-e ./local-package/ # editable install (changes reflect without reinstalling)
file:///absolute/path/to/package
# Direct URLs
https://example.com/mypackage-1.0.0-py3-none-any.whl
# From a different index (private PyPI, artifact repository)
--index-url https://pypi.example.com/simple
--extra-index-url https://pypi.example.com/simple
Including Other Requirements Files
-r base.txt # include another requirements file
-r requirements-common.txt
-c constraints.txt # apply version constraints without directly installing (see below)
Common pattern for multi-environment projects:
# requirements-base.txt
requests==2.31.0
pandas==2.2.0
# requirements-dev.txt
-r requirements-base.txt
pytest==8.0.0
black==24.1.0
ruff==0.3.0
# requirements-prod.txt
-r requirements-base.txt
gunicorn==22.0.0
Constraints Files (-c)
A constraints file pins versions for packages if they get installed (e.g., as transitive dependencies), without forcing them to be installed directly — useful for controlling versions across a large dependency tree without listing every top-level package.
# constraints.txt
urllib3<2.0
certifi>=2024.1.1
pip install -r requirements.txt -c constraints.txt
Common pip Commands
pip install -r requirements.txt
pip install -r requirements.txt --no-deps # don't auto-resolve/install dependencies
pip install -r requirements.txt --upgrade
pip install --break-system-packages -r requirements.txt # needed on some modern Debian/Ubuntu-managed Python
pip freeze > requirements.txt # snapshot all currently installed packages (exact pins)
pip freeze --local > requirements.txt # exclude globally-installed packages, venv only
pip list # installed packages
pip list --outdated # what has newer versions available
pip show requests # detailed info about an installed package
pip check # verify installed packages have compatible dependencies
pip uninstall requests
pip download -r requirements.txt -d ./packages/ # download without installing (offline installs)
pip install --no-cache-dir -r requirements.txt # skip pip's local cache (useful in Docker builds)
pip install --target ./vendor -r requirements.txt # install into a specific directory
pip freeze vs Hand-Written requirements.txt
pip freeze output |
Hand-written | |
|---|---|---|
| Pins | Everything, including transitive deps, at exact versions | Usually just direct/top-level deps |
| Reproducibility | Very high — exact environment snapshot | Depends on how tightly you pin |
| Readability | Poor — hundreds of lines including things you didn’t directly choose | Good — shows intent |
| Best used for | Lock files, CI reproducibility, Docker builds | Source of truth for what your project actually depends on |
Common pattern: maintain a hand-written requirements.in (or just requirements.txt with loose/compatible pins) describing direct dependencies, then compile a fully pinned lock file with pip-tools.
pip-tools Workflow (recommended for reproducible builds)
pip install pip-tools
# requirements.in — your direct, loosely-pinned dependencies
echo "requests>=2.31" >> requirements.in
echo "pandas>=2.2" >> requirements.in
pip-compile requirements.in # generates a fully pinned requirements.txt
pip-compile --upgrade requirements.in # regenerate with latest compatible versions
pip-compile --upgrade-package requests requirements.in # upgrade just one package
pip-sync requirements.txt # install EXACTLY what's pinned, removing anything extra
Docker Best Practice
# Copy requirements first to leverage layer caching — dependencies rarely change as often as source code
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
Common Gotchas
- Unpinned dependencies (
requestswith no version) can silently break a deployment when a new major version is released upstream — pin at least a compatible range (~=) in anything beyond a quick experiment. pip freezeoutput mixes your direct dependencies with every transitive one, making it hard to tell what you actually chose vs what came along for the ride — considerpipdeptreeto visualize the dependency graph.- Comments after a package on the same line are NOT supported the way they are in many other formats — put comments on their own line.
- Environment markers use
and/or, not&&/||— and need to be valid PEP 508 syntax exactly. - Two requirements files listing conflicting version pins for the same package will cause a resolution error —
-c constraints.txtis often cleaner than trying to reconcile conflicting-rincludes. requirements.txthas no built-in concept of dependency groups (dev vs prod) — that’s purely a convention achieved via multiple files and-rincludes, or by moving topyproject.toml+ a tool like Poetry/PDM that has native optional-dependency groups.