Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Dependency Management

Lock Files and Reproducible Installs

Learn why Python projects need lock files, how pip freeze, pip-compile, uv lock and Poetry produce them, and how hash checking makes installs reproducible.

Your code works on your laptop today. Next month a teammate runs pip install -r requirements.txt and gets a different version of a transitive dependency that was released last week, and a test starts failing. Nothing in your code changed. This is the classic "works on my machine" problem, and the cure is a lock file: a complete, exact record of every package version (and ideally its file hash) that you tested with.

This lesson explains the difference between declared and locked dependencies, shows the main tools, and lets you build and verify a hash-checked lock file yourself.

Declared versus locked

There are two layers, and they answer different questions.

Declared dependencies Locked dependencies
Where pyproject.toml (dependencies = [...]) uv.lock, poetry.lock, pylock.toml, or a pinned requirements.txt
Contains Direct dependencies, wide ranges Every package, direct and transitive, with exact versions
Written by You A tool, from the declared list
Question answered "What does my project need?" "Exactly what did we test with?"
Edited by hand? Yes No, regenerate it

Libraries publish the first and usually do not ship a lock file (their users resolve for themselves). Applications, services, scripts and CI jobs should commit both.

flowchart LR
    A["pyproject.toml<br/>wide ranges"] -->|resolve| B["lock file<br/>exact versions + hashes"]
    B -->|install exactly| C["dev laptop"]
    B -->|install exactly| D["CI"]
    B -->|install exactly| E["production image"]

One resolution step, many identical installs.

Pinning with pip

The oldest technique is to freeze an environment:

Terminal
pip freeze > requirements.txt

pip freeze lists every installed package as name==version. It works, but it has two weaknesses: it records whatever happens to be installed (including tools you only used once), and it cannot tell direct dependencies from transitive ones. The tool pip-tools fixes this: you list only what you need in requirements.in, and it computes the pinned file.

Terminal
pip install pip-tools
pip-compile requirements.in --generate-hashes -o requirements.txt
pip-sync requirements.txt        # make the environment match exactly

You can emulate pip freeze using the metadata the interpreter keeps for every package:

Python Freeze the installed packages

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.

Modern lock files

Newer tools resolve and lock in one step and store much more information (Python version, markers per platform, hashes, sources):

Terminal
# uv
uv lock              # create or update uv.lock
uv sync              # install exactly what uv.lock says
uv sync --frozen     # error instead of re-locking if the lock is out of date

# Poetry
poetry lock          # create poetry.lock
poetry install       # install from the lock

# PDM
pdm lock && pdm sync

These files are universal: a single lock can describe versions for Linux, macOS and Windows and for several Python versions at once, using markers. That is a big improvement over a pinned requirements.txt, which is valid for only the platform it was generated on.

There is also a standard format. PEP 751 defines pylock.toml, a tool-independent lock file so that different installers and services can read the same file. Support in installers is still growing, so check your tool's documentation for what it can read and write today.

Commit your lock file to version control and review changes to it like code. A pull request that bumps one dependency should show a small, understandable diff in the lock file.

Hashes: trust but verify

A version number says which release, not which bytes. A hash in the lock file closes that gap: pip computes the SHA-256 of every downloaded file and rejects anything that differs. This protects against a tampered mirror, a compromised download, or a maintainer replacing a file on the index.

With --require-hashes (or when any requirement has a --hash), pip switches to a strict mode: every package must be pinned with == and every file must match one of the listed hashes.

TEXT
requests==2.31.0 \
    --hash=sha256:58cd2187c01e70e6e26505bca751777aa9f2ee0b7e2... \
    --hash=sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af0...

You will build the same mechanism below with hashlib.

Python Build and verify a hash-pinned lock

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 tampered and unlisted files are rejected. That is exactly what pip install --require-hashes does with real wheels.

Keeping a lock file healthy

  • Regenerate on purpose. uv lock --upgrade or pip-compile --upgrade moves everything forward; add a package name to move just one. Automate this with a scheduled job or a bot such as Dependabot or Renovate so updates arrive as small reviewable pull requests.
  • Install from the lock in CI (uv sync --frozen, poetry install, pip install --require-hashes -r requirements.txt) so the tested environment equals the deployed one.
  • Fail when the lock is stale. uv lock --check and poetry check --lock exit with an error if pyproject.toml and the lock disagree.
  • Lock more than runtime. Test, lint and docs dependencies belong in the lock too, in their own groups (see dependency groups), so contributors get the same tools you do.
  • Separate environments, separate locks only if their requirements truly conflict.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these belongs in a lock file but not in the declared dependencies?

    Declared dependencies list what you need in broad terms. A lock file records every resolved package, including transitive ones, with exact versions and hashes.
  2. 2. What does pip do in --require-hashes mode?

    Every requirement must be pinned with == and each downloaded file must match a listed hash, otherwise installation stops.
  3. 3. Why is pip freeze weaker than a lock tool like uv or pip-compile?

    Freeze is a snapshot of one environment. It cannot say which packages you asked for, and its output may not be valid on another platform.
  4. 4. Should a published library normally commit a lock file for its users to install?

    Installers do not read a library's lock file when someone depends on it. The lock still helps the library's own development and CI.

Summary

  • Declared dependencies say what you need; a lock file says exactly what you used, including transitive packages.
  • pip freeze, pip-compile, uv lock, poetry lock and pdm lock create pins; PEP 751 pylock.toml is the standard format.
  • Hashes make installs verifiable: any changed or unexpected file is refused.
  • Commit the lock, install from it everywhere, update it deliberately and automatically.

Next: pip, uv, Poetry and PDM Compared