DANDI Notebooks

Running Notebooks with Docker

← Back to the notebook index

Why These Containers Exist

Every notebook on the index that carries a docker badge is also published as a container image: a frozen, self-contained copy of the notebook together with the exact versions of Python and every package it needs, plus a JupyterLab server to run it in. The "Open in Colab" button is the quickest way to try a notebook, but Colab's environment changes over time as Google updates it, and package versions on PyPI drift. A container does not change. Each image is only published after the notebook has been executed successfully inside it, so what you download is a verified snapshot that will still run years from now, on any machine that can run Docker.

What Docker Is

Docker is a widely used tool for running software in containers: lightweight, isolated environments that bundle a program with everything it needs. You can think of a container image as a snapshot of a small, pre-configured computer. When you run it, Docker starts that computer as an isolated process on your machine, without touching your own Python installation, packages, or files. When the container stops, your system is exactly as it was before.

Installing Docker

On macOS and Windows, install Docker Desktop and launch it (it must be running before you use docker commands). On Linux, install Docker Engine from your package manager. To check that it works, open a terminal and run: 

docker run hello-world

The images are built for both Intel/AMD and ARM processors, so they run natively on Apple Silicon Macs as well as on Intel machines and Linux servers.

Running a Specific Notebook

  1. On the notebook index, find the notebook you want and click its docker badge. This copies a ready-to-use command to your clipboard.
  2. Open a terminal and paste the command. It looks like this:
docker run --rm -p 127.0.0.1:8888:8888 ghcr.io/dandi/example-notebooks/001550-paganlab:latest
  1. The first run downloads the image (typically a few hundred MB to around 1 GB; later runs start instantly). Docker then starts JupyterLab and prints a URL of the form http://127.0.0.1:8888/lab?token=....
  2. Open that URL in your browser, token and all. JupyterLab opens on the notebook with every dependency already installed. The "Installing requirements" cell at the top is only needed on Colab and can be skipped. Run the remaining cells normally.
  3. When you are done, press Ctrl-C in the terminal to stop the container.

The notebooks stream their data directly from the DANDI Archive, so an internet connection is still needed while the notebook runs; the data is not baked into the image.

Common Questions