Pinning ML dependencies

Setup#

No installs needed beyond what is already on your machine — this inspects versions that are already there.

Checking what is actually installed, and catching a real mismatch#

import sys

import numpy
import sklearn

# What is actually installed, right now, on this machine.
installed = {
    "python": sys.version.split()[0],
    "numpy": numpy.__version__,
    "scikit-learn": sklearn.__version__,
}
print("installed right now:", installed)


def check_environment(recorded, installed):
    """Compares the versions an artifact was trained with against what is
    installed now. Loading a model in the wrong environment is how
    'it worked on my machine' becomes a production incident."""
    problems = [
        f"{lib}: trained with {recorded[lib]}, running {installed[lib]}"
        for lib in recorded
        if recorded[lib] != installed.get(lib)
    ]
    return problems


# an artifact trained on the current machine: everything matches
same_env = check_environment(installed, installed)
print("\nartifact trained here, loaded here:", same_env or "no mismatches")

# an artifact whose metadata says it was trained on an older scikit-learn
old_artifact_metadata = {**installed, "scikit-learn": "1.2.0"}
mismatches = check_environment(old_artifact_metadata, installed)
print("\nartifact trained on scikit-learn 1.2.0, loaded here:")
for m in mismatches:
    print(" ", m)

# what requirements.txt should contain: name==exact-version, not a bare name
print("\nwhat requirements.txt should contain, exactly:")
for lib, version in installed.items():
    if lib != "python":
        print(f"  {lib}=={version}")

installed right now: {'python': '3.10.11', 'numpy': '1.26.4', 'scikit-learn': '1.7.2'}

artifact trained here, loaded here: no mismatches

artifact trained on scikit-learn 1.2.0, loaded here:
  scikit-learn: trained with 1.2.0, running 1.7.2

what requirements.txt should contain, exactly:
  numpy==1.26.4
  scikit-learn==1.7.2

The specific version numbers reflect what is installed on the machine that ran this — yours will very likely differ, and that is expected. The comparison logic and its output shape are exact regardless of which versions you actually have.

Walking through it#

installed is read from the libraries themselves, via __version__, not typed in by hand. This is the same information pip show <package> reports, read programmatically instead of by eye. It is the honest way to know what is really running, rather than what a file claims should be running.

check_environment compares two dictionaries and reports only the differences. This is the same check that belongs inside a real model loader. Before trusting a model file, confirm the environment reading it back matches, at least closely, the one that wrote it.

The mismatch example is deliberately artificial. old_artifact_metadata is constructed by hand here. It stands in for what a real packaged artifact's metadata would report, if it had genuinely been trained under an older library version.

Common mistakes#

Pinning only the libraries you directly import. Your direct dependencies have their own dependencies, which also change over time. A full pin — often generated by a lockfile tool — covers the whole tree, not only the packages your code names in an import line.

Never re-pinning at all. A requirements.txt frozen three years ago and never revisited misses every security fix released since. Schedule pin updates — quarterly is a reasonable default — rather than either updating constantly or never.

Pinning in development, but not in the container that actually ships. A Dockerfile that runs pip install -r requirements.txt only guarantees reproducibility if requirements.txt itself is fully pinned. It is the same discipline from Docker for ML, applied specifically to the dependency list rather than the whole image.

Assuming a pinned version pins everything about behaviour. Some libraries depend on system-level pieces — a BLAS implementation, a compiler, a CUDA version — that a Python-level pin does not touch at all. Training and serving environment parity covers this gap in more depth.

Try it yourself#

Change old_artifact_metadata to instead simulate a numpy mismatch instead of scikit-learn, and rerun. Notice the function needed no changes at all — check_environment was written generically over whatever keys the two dictionaries happen to share.

What to learn next#

• Shrinking ML container images — the layer where these pinned dependencies actually get installed and shipped.
• Training and serving environment parity — what still goes wrong even when every version is pinned correctly.
• Docker for ML — packaging the pinned environment itself into something portable.