pip requirements.txt File: Create, Install, and Use with pip

A requirements.txt file is the usual way to pin what your Python app or library needs so teammates, CI, and servers can install the same stack with one command. This page explains what the file is, how pip install -r works, how to author and freeze it, how version markers and comments work, how to pull from Git or local paths, how it fits with virtual environments, and how it compares to constraints.txt and pyproject.toml. For packaging your own project, see create a Python package; for writing files from code, see write to file in Python.

If pip is missing in your shell, see zsh command not found pip (the same ideas apply on other shells).

Tested on: Python 3.13.3; pip 25.0; kernel 6.14.0-37-generic.

What is a pip requirements.txt file?

Think of a requirements file as a shopping list for pip: a plain-text document that names third-party libraries (and sometimes exact versions or download locations) so pip can fetch wheels or sdists from PyPI or from URLs you list. Pip does not execute Python inside the file; it only parses lines and turns each valid line into an install request.

Concretely, each non-empty line that is not a comment is usually one of these shapes:

• A PyPI-style requirement, such as requests==2.32.3 or numpy>=1.26,<2—a package name plus optional PEP 508 version markers.
• A direct reference, such as a git+https://… URL or a path to a local project, telling pip to install from that source instead of (or in addition to) a simple name on PyPI.
• An include, such as -r other.txt, which pulls in another file’s lines as part of the same install run.

The conventional filename is requirements.txt, but the name is only convention—you pass the path to pip install -r. Nothing in Python imports requirements.txt as code; it is data for the installer, like a manifest.

Why use a requirements.txt file?

You use it so every environment agrees on which libraries to install without everyone memorizing the same pip install … command:

• Onboarding: a new developer clones the repo, creates a venv, runs pip install -r requirements.txt, and gets the same dependency set the team tested against.
• Automation: CI pipelines, Docker images, and deployment scripts can run that one command instead of a long, easy-to-drift shell script.
• Reproducibility: version pins (or narrow ranges) reduce “works on my machine” surprises when PyPI publishes newer releases.
• Documentation: the file is a single, reviewable artifact that states what the application or tool stack expects, separate from import statements in your code.

Libraries you publish to PyPI often declare dependencies in pyproject.toml; applications and internal repos still commonly ship a requirements.txt (or several layered files) for the reasons above. Later sections show how to author, freeze, and combine those files safely.

Install packages from requirements.txt using pip

From the directory that contains the file (or with a path to it):

python -m pip install -r requirements.txt

Using python -m pip avoids picking up a pip from a different interpreter. On Windows the same pattern works with the py launcher or python.exe you intend to use.

What does -r mean in pip install -r requirements.txt?

The -r (or --requirement) flag means “read requirements from this file.” Pip parses each line and installs the listed requirements in dependency order. Without -r, arguments on the command line are interpreted as single package names or PEP 508 URLs, not as a file path.

You can pass multiple files: pip install -r base.txt -r dev.txt.

Create a requirements.txt file manually

Create an empty file, name it requirements.txt (or any name), and add one requirement per line. Minimal example:

requests>=2.28.0
click~=8.1.0

Commit the file next to your application or library. Prefer listing direct dependencies you import; let pip resolve transitive packages unless you need to pin them for reproducibility.

Generate requirements.txt using pip freeze

To snapshot everything installed in the current environment:

pip freeze > requirements.txt

freeze emits exact pins (==) for all installed distributions, which is great for reproducing a known-good machine but often too noisy for a hand-maintained app. Many teams run freeze into requirements-lock.txt (or use a dedicated lock tool) and keep a shorter requirements.txt for top-level deps only.

requirements.txt syntax and version specifiers

Pip follows PEP 440 for version specifiers. Multiple conditions on one line are separated by commas (logical AND).

Exact version, minimum version, and version range

numpy==1.26.4
pandas>=2.0.0
scipy>=1.10,<2.0

== pins exactly; >= sets a lower bound; < sets an upper bound. Combining them defines a allowed interval.

Exclude a package version

urllib3!=2.0.0

Useful when one release is broken but neighbors are fine.

Compatible release (~=)

black~=24.0

Roughly means “allow newer versions that match the same release segment,” similar to >=24.0,==24.* for a two-segment version.

Add comments in requirements.txt

Lines starting with # are comments. Inline text after a requirement is not treated as a comment by pip—put notes on their own # lines above the requirement.

# HTTP client used by the worker
httpx>=0.27.0

Install packages from GitHub, URL, or local path

Install from GitHub repository

Use a PEP 508 direct reference (modern style) or the legacy git+https form. Example direct reference:

some-package @ git+https://github.com/org/[email protected]

Replace some-package with the import name / metadata name the project declares. See install Python package from GitHub for branch, tag, and subdirectory patterns.

Install from a local project path

Editable install while developing:

-e ./mylib

Points to a directory with pyproject.toml or setup.py. Non-editable: pip install ./mylib without -e.

Install from another requirements file

Include one file from another with a line that starts with -r:

-r requirements-base.txt
pytest>=8.0.0

Pip inlines the referenced file as if its lines appeared in place—handy for requirements-dev.txt layering on top of production deps.

Use requirements.txt with a virtual environment

Always install project dependencies into a virtual environment so you do not fight the system Python (PEP 668 on many distros).

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

On Windows: .venv\Scripts\activate then the same pip install -r command.

requirements.txt vs constraints.txt

• requirements.txt (with pip install -r) declares packages to install.
• constraints.txt (with pip install -c constraints.txt) caps versions for the resolver but does not, by itself, add new packages—every name in the constraints file should still be requested elsewhere (another -r file or the command line).

Typical pattern: pip install -r requirements.txt -c constraints.txt to keep a short requirements list while pinning transitive versions for CI reproducibility.

requirements.txt vs pyproject.toml

Modern projects declare metadata in pyproject.toml ([project] / dependencies and optional [project.optional-dependencies]). That is the source of truth for installable packages; requirements.txt remains popular for apps, deployment, and quick pins. You can generate a requirements file from metadata with tools like pip-compile (from pip-tools) or export from your lockfile workflow—there is no single mandated mapping.

Common errors with pip requirements.txt

requirements.txt file not found

Usually the shell cwd is wrong or the path is misspelled. Use an explicit path: pip install -r path/to/requirements.txt, or change directory first. Printing pwd (POSIX) or cd (Windows cd) confirms where relative paths resolve.

pip command not found

Install pip for that interpreter (python -m ensurepip --upgrade where available) or use python -m pip. See zsh command not found pip.

No matching distribution found

Often a Python version mismatch (package has no wheel for your OS/Python), a typo in the package name, or a private index without --extra-index-url. Read the full error: pip names the version file or platform tag it could not satisfy.

Permission denied or externally managed environment

On PEP 668–protected system Pythons, pip refuses to write into dist-packages. Fix: create and use a venv (recommended), or install with your OS package manager. Avoid --break-system-packages on machines you care about.

Dependency conflict while installing requirements

The resolver reports which requirement clauses disagree. Relax one pin, align upper/lower bounds, or split optional stacks into a second requirements file installed only where needed.

pip requirements.txt quick reference table

Summary

A requirements.txt file lists Python packages (with optional PEP 440 version clauses, comments, includes, and direct URLs) so pip install -r can recreate an environment. The -r flag simply points pip at that file. Author it by hand for clarity, or start from pip freeze when you need a full snapshot—then trim or layer with extra -r files for dev tools. Combine it with a virtual environment to avoid system-site conflicts and PEP 668 errors. For advanced workflows, pair requirements with constraints.txt for transitive caps and prefer pyproject.toml for published package metadata, exporting or compiling to text when deployment still wants a flat list.

References

• pip User Guide — Requirements files
• PEP 508 — Dependency specification
• PEP 440 — Version specifiers
• PEP 668 — Marking Python base environments as externally managed