How to Pin Exact Package Versions in an Anaconda environment.yml File

The Problem: Silent Package Updates Break Projects

You finish a data analysis script on your laptop, share the folder with a teammate, and it fails immediately. The cause is usually not your code—it is a floating dependency. When you install packages without exact versions, conda may pull in newer releases that change APIs or drop support for older Python versions. A single environment.yml file that pins every critical package solves this by turning your environment into a version-controlled artifact.

Desired Outcome

A portable, version-controlled environment that can be recreated on any machine with a single command: conda env create -f environment.yml. This file lives in your project repository so collaborators and CI systems build the same stack every time.

Prerequisites

• Anaconda or Miniconda installed, with conda version 4.6 or later.
• Basic shell access (Terminal, PowerShell, or Anaconda Prompt).
• A project directory where the environment.yml file will reside.

Writing the environment.yml File

Create a file named environment.yml in your project root. The file uses YAML, a human-readable data format. Start with a top-level name, then list channels and dependencies.

Pin exact versions using the equals sign. For example, numpy=1.24.3 tells conda to install that specific build, not the latest. If you omit the version, conda resolves to the newest compatible release, which reintroduces the reproducibility problem.

Add conda-forge under channels: when you need community-maintained packages that are not in the default Anaconda channel. Conda searches channels in order, so place the most specific channel first.

name: myproject
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.10.13
  - numpy=1.24.3
  - pandas=2.0.3
  - scikit-learn=1.3.0
  - matplotlib=3.7.2

If your project requires a pip-only package, list it under dependencies: using the pip key. Do not run pip install manually after creating the environment; that bypasses the file and breaks reproducibility.

dependencies:
  - python=3.10.13
  - numpy=1.24.3
  - pip
  - pip:
    - requests==2.31.0

Creating and Activating the Environment

Open your shell. On Windows, use Anaconda Prompt or PowerShell; on macOS and Linux, use Terminal. You do not need administrator or root privileges because conda installs into your user directory by default.

Navigate to the project directory and run:

conda env create -f environment.yml

Conda downloads the specified packages and resolves their dependencies. This can take several minutes. When the prompt returns, activate the environment:

conda activate myproject

Replace myproject with the name you chose. The shell prompt should change to show the active environment name.

Expected Checks

Confirm the environment exists and is active:

conda info --envs

The active environment is marked with an asterisk. Next, verify that the installed versions match your pins:

conda list

Scan the output for numpy, pandas, and python. The version column should match the values in your environment.yml.

Finally, run a smoke test. Create a short script that imports each major dependency and prints its version:

import numpy, pandas, sklearn, matplotlib
print("numpy", numpy.__version__)
print("pandas", pandas.__version__)
print("sklearn", sklearn.__version__)
print("matplotlib", matplotlib.__version__)

Execute it with python smoke_test.py. If every import succeeds and the versions match your pins, the environment is functional.

Recovery Options

If conda env create fails partway through—often because two pinned packages require incompatible versions of a shared dependency—you may be left with a partial environment. Remove it before retrying:

conda env remove -n myproject

Then edit environment.yml to relax one of the conflicting pins or adjust the Python version, and run conda env create again.

If you modify an existing environment and it becomes unstable, conda keeps a revision history. View it with:

conda list --revisions

Roll back to a known good state by specifying the revision number:

conda install --revision 3

Replace 3 with the revision shown in the history. This changes the active environment, so use it only when you need to undo recent changes.

Verification and Limitations

To confirm that the recreated environment matches your original, export it and compare:

conda env export > exported.yml

The exported file includes every transitive dependency and the exact build string. It is larger than your hand-written file, but you can diff the two to ensure no critical package is missing.

For stricter cross-machine reproducibility, generate an explicit spec file that records exact download URLs and build hashes:

conda list --explicit > spec.txt

Recreate from it with conda create --name myproject --file spec.txt. This is more rigid than environment.yml because it does not re-resolve dependencies; it installs exactly what was recorded.

Limitations: conda packages are platform-specific. An environment.yml created on macOS may fail on Windows if it contains packages without builds for that operating system. Pinning exact versions also means you will not receive security patches automatically; you must update the file deliberately. Finally, mixing pip and conda packages increases the risk of solver conflicts, so keep pip dependencies inside the dependencies: section rather than installing them ad hoc.

Practical Result Check

The definitive test is to clone your project into a fresh directory on another machine (or a clean CI runner), run conda env create -f environment.yml, activate the environment, and execute your smoke test. If the script runs without import errors and prints the expected versions, your environment definition is reproducible.