Add a Conda Environment

Contributor guide

Author

ESIIL Team

Published

May 30, 2026

This site uses per-platform lockfiles to keep builds reproducible across macOS and Ubuntu. Contributors add a base environment file, then we generate lockfiles from it.

For local development, we recommend rendering with the dev profile so you only set up the kernel needed for the page you are working on:

quarto render path/to/page.qmd --profile dev

1. Add a base environment file

Create a new file under environments/base/ with a descriptive name, for example:

environments/base/your-module.yml

Include:

  • name: a short, lowercase, hyphenated environment name
  • channels: (prefer conda-forge)
  • dependencies: only the packages you need

Avoid pinning exact builds or platform-specific packages in the base file.

2. Generate or update the lockfile

The site build runs:

scripts/install_kernelspec.sh

That script creates a lockfile for your current platform in environments/locks/ and installs the environment from it.

To clear old lockfiles and regenerate them during render:

rm -f environments/locks/*.yml && quarto render

To rebuild only one page’s environment after changing its environment/base/*.yml file, set the page as QUARTO_INPUT and ask the installer to regenerate that page’s lockfile and recreate that page’s environment:

QUARTO_INPUT=path/to/page.qmd \
REGENERATE_LOCKFILES=true \
RECREATE_ENVS=true \
scripts/install_kernelspec.sh

If conda-lock is not installed, bootstrap the tooling environment first:

conda env create -f environments/tools.yml

Single-page renders (dev profile)

For local development, use the dev profile to avoid installing every environment. The pre-render step will only set up the kernel referenced in the page you are rendering (or the site default if none is specified):

quarto render path/to/page.qmd --profile dev

3. Specify the kernel in your notebook

In your .qmd file header, set the kernel name to match your conda environment:

---
title: "Your Lesson Title"
jupyter:
  kernelspec:
    name: your-env-name
---

Use the same name value as in your environments/base/*.yml file.

Application-level dependencies

Some lessons need software that is not just a Python or R package. For example, an LLM lesson might use a conda environment for the Python client packages, but also require the Ollama application and a downloaded model.

When that happens:

  • keep Python and R packages in the lesson-specific conda environment
  • document operating-system install steps in the lesson
  • add a small helper script when the lesson needs to check, start, or test an external service
  • make GitHub Actions execute the same notebook setup path when refreshing frozen outputs

For Ollama lessons, use scripts/setup_ollama.py from a notebook cell. It prints install instructions for macOS, Windows, and Linux, starts the local Ollama server when available, and can auto-install Ollama on Linux CI when OLLAMA_AUTO_INSTALL=1.