Selecting an Image

Using one of the Jupyter Docker Stacks requires two choices:

  1. Which Docker image you wish to use

  2. How you wish to start Docker containers from that image

This section provides details about the first.

Core Stacks

The Jupyter team maintains a set of Docker image definitions in the https://github.com/jupyter/docker-stacks GitHub repository. The following sections describe these images including their contents, relationships, and versioning strategy.

jupyter/base-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/base-notebook is a small image supporting the options common across all core stacks. It is the basis for all other stacks.

  • Minimally-functional Jupyter Notebook server (e.g., no LaTeX support for saving notebooks as PDFs)

  • Miniforge Python 3.x in /opt/conda with two package managers

    • conda: "cross-platform, language-agnostic binary package manager".

    • mamba: "reimplementation of the conda package manager in C++". We use this package manager by default when installing packages.

  • notebook, jupyterhub and jupyterlab packages

  • No preinstalled scientific computing packages

  • Unprivileged user jovyan (uid=1000, configurable, see options) in group users (gid=100) with ownership over the /home/jovyan and /opt/conda paths

  • tini as the container entrypoint and a start-notebook.sh script as the default command

  • A start-singleuser.sh script useful for launching containers in JupyterHub

  • A start.sh script useful for running alternative commands in the container (e.g. ipython, jupyter kernelgateway, jupyter lab)

  • Options for a self-signed HTTPS certificate and passwordless sudo

jupyter/minimal-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/minimal-notebook adds command line tools useful when working in Jupyter applications.

  • Everything in jupyter/base-notebook

  • TeX Live for notebook document conversion

  • git, vi (actually vim-tiny), nano (actually nano-tiny), tzdata, and unzip

jupyter/r-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/r-notebook includes popular packages from the R ecosystem.

jupyter/scipy-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/scipy-notebook includes popular packages from the scientific Python ecosystem.

jupyter/tensorflow-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/tensorflow-notebook includes popular Python deep learning libraries.

  • Everything in jupyter/scipy-notebook and its ancestor images

  • tensorflow machine learning library

jupyter/datascience-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/datascience-notebook includes libraries for data analysis from the Julia, Python, and R communities.

  • Everything in the jupyter/scipy-notebook and jupyter/r-notebook images, and their ancestor images

  • rpy2 package

  • The Julia compiler and base environment

  • IJulia to support Julia code in Jupyter notebooks

  • HDF5, Gadfly, RDatasets packages

jupyter/pyspark-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/pyspark-notebook includes Python support for Apache Spark.

  • Everything in jupyter/scipy-notebook and its ancestor images

  • Apache Spark with Hadoop binaries

  • pyarrow library

jupyter/all-spark-notebook

Source on GitHub | Dockerfile commit history | Docker Hub image tags

jupyter/all-spark-notebook includes Python, R, and Scala support for Apache Spark.

Image Relationships

The following diagram depicts the build dependency tree of the core images. (i.e., the FROM statements in their Dockerfiles). Any given image inherits the complete content of all ancestor images pointing to it.

Image inheritancediagram

Builds

Every Monday and whenever a pull requests is merged, images are rebuilt and pushed to the public container registry.

Versioning via image tags

Whenever a docker image is pushed to the container registry, it is tagged with:

  • a latest tag

  • a 12-character git commit SHA like b9f6ce795cfc

  • a date formatted like 2021-08-29

  • a set of software version tags like python-3.9.6 and lab-3.0.16

For stability and reproducibility, you should either reference a date formatted tag from a date before the current date (in UTC time) or a git commit SHA older than the latest git commit SHA in the default branch of the jupyter/docker-stacks GitHub repository.

Community Stacks

The core stacks are just a tiny sample of what's possible when combining Jupyter with other technologies. We encourage members of the Jupyter community to create their own stacks based on the core images and link them below.

See the contributing guide for information about how to create your own Jupyter Docker Stack.