Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 39 ยท Reproducibility

Pinning Dependencies and Requirement Files

Record exact package versions with requirements.txt, constraints, lock files and environment.yml so a notebook can be rebuilt years later with the same results.

A virtual environment isolates a project, but it does not remember itself. If your only record of the environment is the folder on your disk, a new laptop or a teammate starts from zero. A requirements file is the recipe: a text file listing which packages, and which versions, the notebook needs.

This lesson covers the common formats, the difference between loose and pinned versions, and a way to check an environment against its recipe. The commands are read-only here; the runnable cells parse and compare requirement text in plain Python.

Loose versus pinned

A loose requirement allows a range; a pinned requirement fixes one version.

TEXT
# requirements.in  (what you ask for)
pandas>=2.2
matplotlib
jupyterlab

# requirements.txt (what you actually got, pinned)
pandas==2.2.3
numpy==2.1.3
matplotlib==3.9.2
python-dateutil==2.9.0.post0

You write the short list of direct dependencies. Tools resolve everything those need (numpy, dateutil, and so on) into the long, fully pinned list. Install from the pinned file to get the same environment everywhere.

Terminal
pip freeze > requirements.txt      # quick snapshot of the current environment
pip install -r requirements.txt    # rebuild it elsewhere

pip freeze is the simplest option but captures everything, including tools you installed for other reasons. A tidier workflow keeps the short requirements.in and compiles it:

Terminal
pip install pip-tools
pip-compile requirements.in         # writes requirements.txt
pip-sync requirements.txt           # makes the environment match exactly

uv offers the same flow (uv pip compile, uv pip sync) and is much faster. Whichever tool you pick, commit both the short file and the pinned file.

Version specifiers

Specifier Meaning
pandas==2.2.3 exactly this version
pandas>=2.2,<3 any 2.x from 2.2 up
pandas~=2.2 compatible release: >=2.2, ==2.*
pandas!=2.2.0 anything except a known bad release

For notebooks you share as results, pin exactly. For a library you publish, use ranges instead, so others can combine it with their packages.

Conda: environment.yml

Conda projects use a YAML file:

YAML
name: sales-analysis
channels:
  - conda-forge
dependencies:
  - python=3.12
  - pandas=2.2
  - matplotlib=3.9
  - jupyterlab
  - pip
  - pip:
      - some-pip-only-package==1.4.0
Terminal
conda env create -f environment.yml
conda env export --from-history > environment.yml   # only what you asked for

--from-history keeps the file portable across operating systems. A full export lists platform-specific build strings and often fails on another OS.

Pin the Python version too

Libraries behave differently across Python releases, so record the interpreter. In pyproject.toml use requires-python = ">=3.12,<3.13", in conda python=3.12, and in a .python-version file the exact version for tools that read it.

Parse a requirements file

Understanding the format makes the tools less magical. The runnable cell parses lines into names and specifiers, and flags lines that are not pinned.

Python Parse and audit a requirements file

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.

Only pandas is pinned. A notebook rebuilt from this file could receive different numpy or matplotlib versions next month, which is how silent result changes begin.

Compare an environment with its recipe

The second stand-in checks installed versions against pins and reports drift. This is what pip-sync and CI checks do in a larger form.

Python Detect drift from pinned versions

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 pins are deliberately impossible (99.0.0), so every package reports a problem. Put a check like this in the first cell of a critical notebook, and it fails loudly instead of producing slightly different numbers.

Hashes and lock files

Pinned versions say which release; hashes say which exact file. pip-compile --generate-hashes adds --hash=sha256:... to each line, and pip install then refuses a tampered or swapped download. Modern tools (uv lock, poetry lock, pdm lock) produce a lock file that holds the complete resolved graph, and you commit it.

Keep Jupyter out of the analysis requirements

Your analysis needs pandas and matplotlib. It does not need JupyterLab itself, because the person who only runs the code in a script or a server may not use the interface. Keep tools in a separate requirements-dev.txt, or in an optional dependency group.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main benefit of a pinned requirements file?

    Exact versions mean the same code and libraries run everywhere, which keeps results stable.
  2. 2. What does pandas~=2.2 allow?

    The compatible-release operator means >=2.2, ==2.*.
  3. 3. Why prefer conda env export --from-history?

    A full export includes platform-specific builds that often fail on another operating system.
  4. 4. What do hashes in a requirements file add?

    pip compares each downloaded file with its recorded sha256 and rejects a mismatch.

Summary

  • Commit a short list of direct dependencies and a fully pinned list or lock file.
  • Pin exact versions for results you must reproduce; use ranges for libraries you publish.
  • Conda projects use environment.yml; record the Python version as well.
  • Check an environment against its pins early in the notebook.

Next: Hidden State and Restart and Run All