How can dependency versions be pinned in an ML project?

Dependency pinning means choosing and recording specific versions of the software packages an ML project uses, rather than allowing an installer to select a different version whenever someone sets up the project.

This matters because a training script that runs today may behave differently—or fail—after a library upgrade. Pinning helps the team rebuild a known, tested software environment.

A practical example

Imagine a food-delivery team training a model that predicts delivery times. The model's Python code imports numpy, pandas, and scikit-learn.

If the team only writes scikit-learn in its dependencies, two engineers installing the project on different days might receive different versions. A newer version could change an API or the behavior of model loading.

One straightforward approach is to record exact versions in requirements.txt:

# Example versions; choose versions tested by your project
numpy==2.1.3
pandas==2.2.3
scikit-learn==1.6.1

Then create a fresh environment and install them:

BASH
python -m venv .venv
# Activate .venv using the command for your operating system
python -m pip install -r requirements.txt

The == operator asks pip for that exact package version. This is direct dependency pinning.

How should a team pin dependencies?

1. List the packages the application needs. Maintain them in pyproject.toml or a requirements input file. For an installable Python library, compatible version *ranges* may be preferable; a deployable ML application often needs a separately resolved, exact environment.
2. Resolve and record the complete environment. Packages depend on other packages, called *transitive dependencies*. Pinning only three top-level libraries does not guarantee that every dependency version stays the same. A tool such as pip-compile can produce a fully pinned requirements.txt from requirements.in or pyproject.toml.
3. Recreate the environment from the recorded versions. Install the pinned requirements in a clean virtual environment or automated build, then run the project's tests.
4. Record the runtime constraints too. Python version, operating system, CPU/GPU architecture, and accelerator libraries such as CUDA can affect which packages install and how they run. Python package pins alone do not freeze these components.
5. Update deliberately. Check for security fixes and compatibility changes, upgrade selected packages, rerun training or inference checks when needed, and commit the updated dependency record after review.

For a small experiment, python -m pip freeze > requirements.txt captures package versions already installed in the active environment. However, if that environment contains unrelated packages, the output captures those too. A clean environment and a dependency resolver are usually better for a maintained project.

What does pinning actually guarantee?

A line such as scikit-learn==1.6.1 constrains which version of that named package pip installs. It does not, on its own, guarantee:

• The same versions of the package's dependencies.
• Identical Python, operating-system, or GPU environments.
• The same training data, random seeds, or resulting model.
• That an old dependency is secure forever.

For stronger repeatability, teams also record the resolved dependency set, runtime details, input data and training settings. Build hashes and verified package sources can further reduce supply-chain risks.

How is this different from environment parity?

Pinning records specific software versions. Environment parity is the broader goal of making development, staging, and production behave consistently. Pinning is one tool for achieving that goal, not the whole solution.

The next concept explains lockfiles, which record a resolved set of dependencies more systematically.

In short: Pin and test the package versions your ML application relies on, capture indirect dependencies, and update them intentionally. This makes failures easier to diagnose and model releases easier to reproduce.