Using environment.yml to lock Anaconda environments for reproducible builds

The reproducibility problem

When a Python project grows, developers often install packages with conda install or pip install on their laptops. The resulting set of versions can differ from machine to machine, causing “it works on my machine” failures.

Thesis: a single environment.yml file solves this

By declaring exact package versions, channels, and optional pip dependencies in a YAML file, you can recreate the same environment with one command.

Writing a minimal environment.yml

name: myproject
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.11
  - numpy=1.26
  - pip:
    - requests==2.31.0

Place this file in the project root. The channels list ensures conda‑forge is consulted first, reducing the chance of pulling older builds from defaults.

Creating the environment

Run the following command in a terminal where you have Anaconda or Miniconda installed and sufficient user permissions to create environments:

conda env create -f environment.yml

Expected outcome: Conda solves the specifications, downloads the packages, and creates a directory under $HOME/anaconda3/envs/myproject (or the equivalent path for your installation). After completion, activate the environment and verify the installed versions:

conda activate myproject
python -c "import numpy, sys, requests; print('numpy', numpy.__version__); print('requests', requests.__version__)"

If the command prints the versions you specified, the environment matches the file.

Exporting a platform‑specific snapshot

To share a locked version that works on another OS, export the environment without build strings:

conda env export --no-builds > exported.yml

You can then compare exported.yml with the original environment.yml using a diff tool; only the version numbers should differ, confirming reproducibility.

Trade‑off and limitation

Exported files may still contain platform‑specific sub‑dependencies (e.g., libgcc) that cause solve failures on a different OS. Using --from-history when creating the environment from the exported file tells Conda to ignore those hidden dependencies and rely only on the explicitly listed packages.

conda env create -f exported.yml --from-history

This reduces solve time and improves cross‑platform compatibility, but you lose the guarantee that every transitive dependency is exactly the same as in the original environment.

Actionable closing

• Commit environment.yml to your version‑control system.
• In CI pipelines, run conda env create -f environment.yml as a setup step.
• Periodically regenerate exported.yml --no-builds to audit drift.
• If you encounter solve errors on a new platform, retry with --from-history and then add any missing packages explicitly.