Part 3 of 12

Pin Versions and Build Reproducible ML Environments

WalkthroughBy Bot Tutorials · Published Nov 3, 2026 · Facts last verified Nov 3, 2026

ML libraries series complete. "Review Your Training Code with a Bot: Checklist" was the finale. See every part in the series hub.

Part 3: make a venv, pin exact versions with pip freeze, check with pip check, and see a real failed install that pinning would have caught.

Video: Pin Versions and Build Reproducible ML Environments (4:50). Narrated from this guide, with the real code and real output we ran. Captions included (caption file). Prefer reading? Everything in the video is in the guide below.

A machine learning project that works today can break next month without you changing a line, because a library you depend on released a new version. The fix is boring and effective: a virtual environment per project, and a file that pins exact versions. This walkthrough does it with the standard tools, shows real output, and uses a bot to explain what you're looking at.

What the bot can and can't do here

It can:

Explain the difference between a loose requirement like numpy>=2 and a pin like numpy==2.5.4.
Read a long pip error and tell you which line matters.
Draft a README section on recreating the environment.

It can't:

Know which versions work together today. pip's resolver and the libraries' own docs decide that.
See your Python version or platform unless you tell it.
Make a pip error go away by guessing versions. Check each suggestion against the package's install page.

Check first, upgrade second

Pin what works before you upgrade anything. Then upgrade one package at a time in a fresh environment and run your tests.

Step 1: a virtual environment

Python's venv module is part of the standard library, and the Python Packaging Guide recommends virtual environments for project dependencies:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip

Everything you install now goes into .venv, not your system Python.

Step 2: install and freeze

We installed one pinned package and let pip pull in its dependencies:

pip install scikit-learn==1.9.1
pip freeze

The real pip freeze output from a fresh environment on our box, with Python 3.13.5:

cloudpickle==3.1.2
joblib==1.6.0
narwhals==2.28.0
numpy==2.5.4
scikit-learn==1.9.1
scipy==1.18.1
threadpoolctl==3.7.0

One install became seven pinned packages. That's what pip's Repeatable installs page means when it says a frozen requirements file pins "not only the top-level packages, but also all of their transitive dependencies". Save it with pip freeze > requirements.txt and commit it.

Step 3: check the environment is consistent

pip check

On our box it printed No broken requirements found. Run it after every install. It catches packages whose stated dependencies aren't met.

Step 4: a real failure pinning prevents

To show why version choice matters, we asked the same environment for an old NumPy:

pip install "numpy<2"

It failed. pip found no ready-made wheel of NumPy 1.x for Python 3.13 on our box, tried to build it from source, and stopped because there was no C++ compiler. The key line from the real output:

../meson.build:1:0: ERROR: Unknown compiler(s): [['c++'], ['g++'], ['clang++'], ['nvc++'], ['pgc++'], ['icpc'], ['icpx']]
error: metadata-generation-failed

The lesson isn't "install a compiler". It's that Python version and library version have to fit, just like driver and CUDA in Part 1. Each library's install page lists the Python versions it supports. scikit-learn's install page, for example, says scikit-learn 1.7 requires Python 3.10 or newer.

The prompt for pip errors

Here's the full output of a failed pip install (pasted), my Python version and my OS. Which line is the actual cause? Is it a version mismatch, a missing build tool or a network problem? Suggest one change, and tell me which official page confirms it.

What to write down besides requirements.txt

pip freeze doesn't record everything. Add a short note with:

Python version, from python --version.
The install command for GPU builds, for example the exact PyTorch command from its selector, because the CUDA build comes from the index URL, not the version number alone.
The OS and driver, from the Part 1 report.

Stronger options

pip's Repeatable installs page also covers hash-checking, where each requirement carries a --hash so a changed download is refused, and installing with --no-deps so nothing unlisted sneaks in. Use them for anything you share or deploy.

A clean-room test of your pins

The real proof that a requirements file works is to rebuild from it somewhere fresh:

python3 -m venv /tmp/check-env
. /tmp/check-env/bin/activate
pip install -r requirements.txt
pip check
python -m pytest -q

If that passes, someone else on the same Python version and platform can rebuild your setup. If it fails, you've found the problem before a teammate or your future self does. Ask a bot to turn these lines into a small script or a CI step, then read what it wrote before running it.

Upgrading on purpose

When you do want newer versions, upgrade one package at a time in a fresh environment, run pip check and your tests, and freeze again. Read the package's release notes for anything marked as a breaking change. A bot can summarize release notes you paste in, but it shouldn't decide for you whether a change matters to your code.

Tested vs documented

Tested by us: the venv, the freeze output, pip check and the failed NumPy install, all on our box.
Documented, not tested by us: hash-checking mode, from pip's docs.

Where to go next

Tomorrow's three parts start using the libraries: NumPy and pandas, a first scikit-learn model, and PyTorch on the CPU.

Safety, licensing and privacy: read this before you run anything

This series is about learning and small personal projects with machine learning libraries. A bot is a helper, not an authority.

Check bot advice against official docs. Version numbers, install commands and compatibility tables change often. Compare every answer with the PyTorch, TensorFlow, JAX, scikit-learn, NVIDIA, Hugging Face or ONNX Runtime pages we link. If the bot and the docs disagree, the docs win.
Work in a virtual environment. Don't install or remove packages in your system Python, and don't run sudo pip.
Run untrusted files carefully. Pickle-based model files can run code when loaded. Only load models from sources you trust, and prefer safer formats like safetensors where the library supports them.
Respect licenses. Datasets and model weights carry their own licenses and terms. Read the model card and license before you use, share or sell anything built on them. We don't give legal advice; ask a qualified person if it matters.
Protect personal data. Don't paste private, customer or medical data into a bot or a training set unless you have the right to, and check the bot's own privacy settings first.
No hardware claims you didn't measure. Treat any speed figure from a bot as a guess until you've timed it on your own machine.
No medical, legal or financial decisions from a toy model. These guides are for learning only.

FAQ

Why not just pip install the latest?

Because the latest changes. pip's Repeatable installs page explains that pinning protects you from bugs or incompatibilities in newly released versions.

Does pip freeze pin everything?

It pins the top-level packages and all their dependencies, as pip's docs say. It doesn't record the Python version or the CUDA build, so write those down too.

Was this tested?

Yes. The freeze, pip check and the failed numpy install are real output from our box.