What are lockfiles and why are they useful in reproducible ML environments?

A lockfile is a machine-generated record of the exact software dependencies chosen for a project. It helps different developers, automated tests, and deployment systems install the same resolved package versions instead of selecting new versions independently.

In the previous concept, we learned how to pin dependencies. A lockfile builds on that idea: it captures not only the packages you requested, but also the indirect packages those packages need.

A practical example

Imagine a food-delivery team that trains a model to predict delivery times. Its project declares that it needs pandas and scikit-learn.

These are direct dependencies. Each may need additional libraries—for example, scikit-learn depends on packages such as NumPy and SciPy. These additional packages are transitive dependencies.

If developers install from broad version requirements on different dates, the installer may resolve different compatible versions of those indirect libraries. The training script could then behave differently or fail.

A lockfile records the resolved dependency set so the team can recreate the tested installation more reliably.

What is the difference between a dependency declaration and a lockfile?

• Dependency declaration (such as `pyproject.toml`): States *what the project needs*, often using allowed version ranges.
• Lockfile (such as `uv.lock` or `poetry.lock`): Records *which versions were selected* for the dependency graph, with additional metadata that depends on the format.

Think of a dependency declaration as a shopping list and a lockfile as the exact order that was placed—including all the supporting ingredients.

A small Python example using uv

In an existing uv-managed project, the team might run:

BASH
uv add pandas scikit-learn
uv lock
uv sync --locked

Here:

1. uv add records the declared dependencies in pyproject.toml and updates the project's lockfile.
2. uv lock ensures the project's uv.lock is generated or updated.
3. uv sync --locked installs the locked environment only if the lockfile is already consistent with the project requirements. Otherwise it fails rather than silently changing the lockfile.

The team commits both pyproject.toml and uv.lock to Git. The same command can be used in CI/CD so a proposed change is tested against the recorded dependency resolution.

Other tools use similar concepts: Poetry has poetry.lock; the Python packaging ecosystem also specifies a tool-neutral pylock.toml format. These are different formats, so use an installer that supports the one your project produces.

Why are lockfiles valuable in MLOps?

1. Consistent environments: Teammates and CI jobs use the versions selected when the application was tested.
2. Easier debugging: If a new dependency resolution breaks model loading, the team can compare the lockfile changes to see what changed.
3. Controlled upgrades: Libraries change when the team intentionally updates the lockfile, reviews the difference, and reruns tests.
4. Release traceability: A training run can record its Git commit and lockfile revision alongside the dataset, configuration, and model version.
5. Less guesswork during deployment: The build process can install a recorded dependency set instead of solving version choices from scratch.

What does a lockfile *not* guarantee?

A lockfile is a big step toward reproducibility, but it does not guarantee identical ML predictions on its own.

• Runtime and platform still matter: Python version, operating system, CPU/GPU architecture, CUDA drivers, and availability of compatible package builds can affect installation and behavior. Some lockfiles represent multiple supported environments.
• Model inputs still matter: The same packages with different training data, random seeds, or training settings may produce a different model.
• Security still matters: A locked version can develop a known vulnerability. Scan dependencies and refresh them through a tested update process.
• Integrity depends on the format and installer: Some lockfiles record package hashes and other artifact details, but don't assume every lockfile or install workflow offers the same guarantees.

In short: Pinning a few packages restricts version choices; a lockfile records a resolved dependency set. Commit it, install from it in CI and deployments, and update it deliberately to make ML environments more consistent and easier to diagnose.