Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Virtual Environments

Freezing Requirements and Reproducibility

Learn what pip freeze records, how requirements.in and pinned files work, why hashes and constraints matter, and build a requirements file checker live.

You built your project, it works, and now a teammate (or a server) has to run it. "Install the dependencies" is not an answer until the instructions produce the same versions everywhere. This lesson covers the classic tools for that: pip freeze, requirements.txt, constraints, hashes, and the two-file pattern used by pip-tools.

What pip freeze records

pip freeze prints every installed distribution as name==version. It captures the current state of one environment: your direct dependencies and everything they pulled in.

Terminal
(.venv) $ pip install requests
(.venv) $ pip freeze
certifi==2024.8.30
charset-normalizer==3.3.2
idna==3.8
requests==2.32.3
urllib3==2.2.2
(.venv) $ pip freeze > requirements.txt

You can reproduce that output yourself with importlib.metadata, which is exactly the data pip reads.

Python A freeze command built from importlib.metadata

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The result is a snapshot, not a plan. It contains no information about why a package is there. Is urllib3 something you chose or a transitive dependency of requests? After six months nobody remembers, and removing requests leaves its dependencies behind. That is the main weakness of a bare freeze.

Two kinds of files, again

The professional pattern keeps two files:

File Contains Written by
requirements.in (or [project].dependencies) Direct dependencies, loose ranges You
requirements.txt (or a lock file) Every package, exact versions, optional hashes A tool

With pip-tools:

Terminal
pip install pip-tools
echo "requests>=2.30" > requirements.in
pip-compile requirements.in -o requirements.txt --generate-hashes
pip-sync requirements.txt             # make the environment match exactly

The compiled file annotates where every pin came from:

TEXT
certifi==2024.8.30 \
    --hash=sha256:... \
    --hash=sha256:...
    # via requests
requests==2.32.3 \
    --hash=sha256:...
    # via -r requirements.in

uv pip compile produces the same format, and uv lock / poetry lock / pdm lock produce richer lock files with the same idea.

Parsing and checking a requirements file

A requirements file is a list of PEP 508 strings plus pip options (-r other.txt, --index-url ..., --hash=...) and comments. Reading one correctly is a good exercise, and it is useful: you can write a linter that fails CI when someone commits an unpinned dependency.

Python Checking that every line is pinned

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Hashes and why they help

With --require-hashes (implied once any line has --hash), pip insists that every package is pinned with == and that the downloaded file matches one of the hashes you listed. A compromised index or a re-uploaded file will then fail the install instead of silently running. Hashes also make installs deterministic across platforms, because the file for each platform's wheel has its own hash and you list all the ones you support.

You can compute a file hash with a few lines. This is the same SHA-256 that appears in lock files and in the RECORD file inside wheels.

Python Computing and verifying a hash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Constraints files

Sometimes you do not want to request a package, only to limit its version if it is installed. That is what a constraints file is for:

Terminal
pip install -r requirements.txt -c constraints.txt

Constraints never add packages. Large organizations use one shared constraints file to keep dozens of services on compatible versions of security-sensitive libraries, without forcing every service to depend on them.

Reproducibility checklist

A build is reproducible when someone can recreate the same environment from files in the repository. To get there:

  1. Declare direct dependencies loosely in pyproject.toml (or requirements.in).
  2. Lock the full set with exact versions and hashes (pip-compile --generate-hashes, uv lock, poetry lock, pdm lock).
  3. Commit the lock file; review its diff in pull requests.
  4. Install from the lock in CI and production (pip install --require-hashes -r ..., uv sync --frozen).
  5. Record the Python version (.python-version, requires-python, or the Docker base image).
  6. Update on purpose: run a scheduled upgrade job (Renovate, Dependabot, uv lock --upgrade), run tests, merge.
flowchart LR
    A["requirements.in<br/>loose ranges"] -- "pip-compile / uv lock" --> B["lock / requirements.txt<br/>exact + hashes"]
    B -- "install --require-hashes" --> C["identical environment<br/>laptop, CI, server"]
    A -. "upgrade on purpose" .-> A

The loose file expresses intent, the pinned file is the evidence, and installs use the pinned file.

Do not pin every dependency of a library in its published metadata. A library that demands urllib3==2.2.2 conflicts with any app that needs a different release. Pin in lock files for applications; publish ranges for libraries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main drawback of committing a bare pip freeze as your only dependency file?

    A freeze lists everything flat. A direct-dependency file plus a compiled lock keeps intent and evidence separate.
  2. 2. What does pip's --require-hashes mode guarantee?

    It rejects unpinned requirements and any file whose hash is not in the file.
  3. 3. What is a constraints file used for?

    Constraints (-c) only restrict; they never cause an install.
  4. 4. A library you publish should declare its dependencies as:

    Ranges let your library coexist with others. Applications pin exact versions in lock files.

Summary

  • pip freeze snapshots one environment as name==version; it loses the direct-versus-transitive distinction.
  • Keep intent (requirements.in or pyproject.toml) separate from evidence (compiled/lock file with exact versions).
  • pip-compile --generate-hashes, uv lock, poetry lock and pdm lock produce reproducible pins.
  • Hashes make installs tamper-evident; --require-hashes enforces them.
  • Constraints files limit versions without adding packages.
  • Libraries publish ranges; applications pin.

Next: pyproject.toml Basics