Jupyter Docker Stacks#
Jupyter Docker Stacks are a set of ready-to-run Docker images containing Jupyter applications and interactive computing tools. You can use a stack image to do any of the following (and more):
Start a personal Jupyter Server with the JupyterLab frontend (default)
Run JupyterLab for a team using JupyterHub
Start a personal Jupyter Server with the Jupyter Notebook frontend in a local Docker container
Write your own project Dockerfile
Quick Start#
You can try a relatively recent build of the quay.io/jupyter/base-notebook image on mybinder.org. Otherwise, the examples below may help you get started if you have Docker installed, know which Docker image you want to use, and want to launch a single Jupyter Application in a container.
The User Guide on ReadTheDocs describes additional uses and features in detail.
Note
Since 2023-10-20
our images are only pushed to Quay.io
registry.
Older images are available on Docker Hub, but they will no longer be updated.
Example 1#
This command pulls the jupyter/scipy-notebook
image tagged 2024-03-14
from Quay.io if it is not already present on the local host.
It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the container’s internal port 8888
to port 10000
of the host machine:
docker run -p 10000:8888 quay.io/jupyter/scipy-notebook:2024-03-14
You can modify the port on which the container’s port is exposed by changing the value of the -p
option to -p 8888:8888
.
Visiting http://<hostname>:10000/?token=<token>
in a browser loads JupyterLab,
where:
The
hostname
is the name of the computer running DockerThe
token
is the secret token printed in the console.
The container remains intact for restart after the Server exits.
Example 2#
This command pulls the jupyter/datascience-notebook
image tagged 2024-03-14
from Quay.io if it is not already present on the local host.
It then starts an ephemeral container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000.
docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work quay.io/jupyter/datascience-notebook:2024-03-14
The use of the -v
flag in the command mounts the current working directory on the host (${PWD}
in the example command) as /home/jovyan/work
in the container.
The server logs appear in the terminal.
Visiting http://<hostname>:10000/?token=<token>
in a browser loads JupyterLab.
Due to the usage of the --rm
flag
Docker automatically cleans up the container and removes the file system when the container exits,
but any changes made to the ~/work
directory and its files in the container will remain intact on the host.
The -i
flag keeps the container’s STDIN
open, and lets you send input to the container through standard input.
The -t
flag attaches a pseudo-TTY to the container.
Note
By default, jupyter’s root_dir is /home/jovyan
.
So, new notebooks will be saved there, unless you change the directory in the file browser.
To change the default directory, you must specify ServerApp.root_dir
by adding this line to the previous command: start-notebook.py --ServerApp.root_dir=/home/jovyan/work
.
Choosing Jupyter frontend#
JupyterLab is the default for all the Jupyter Docker Stacks images.
It is still possible to switch back to Jupyter Notebook (or to launch a different startup command).
You can achieve this by passing the environment variable DOCKER_STACKS_JUPYTER_CMD=notebook
(or any other valid jupyter
subcommand) at container startup;
more information is available in the documentation.
Resources#
Acknowledgments#
Starting from
2022-07-05
,aarch64
self-hosted runners were sponsored by@mathbunnyru
. Please, consider sponsoring his work on GitHubStarting from
2023-10-31
,aarch64
self-hosted runners are sponsored by an amazing2i2c non-profit organization
CPU Architectures#
We publish containers for both
x86_64
andaarch64
platformsSingle-platform images have either
aarch64-
orx86_64-
tag prefixes, for example,quay.io/jupyter/base-notebook:aarch64-python-3.11.6
Starting from
2022-09-21
, we create multi-platform images (excepttensorflow-notebook
)Starting from
2023-06-01
, we create a multi-platformtensorflow-notebook
image as wellStarting from
2024-03-14
, we create CUDA enabled variant ofpytorch-notebook
image forx86_64
platform
Using old images#
This project only builds one set of images at a time.
If you want to use the older Ubuntu
and/or Python
version, you can use the following images:
Build Date |
Ubuntu |
Python |
Tag |
---|---|---|---|
2022-10-09 |
20.04 |
3.7 |
|
2022-10-09 |
20.04 |
3.8 |
|
2022-10-09 |
20.04 |
3.9 |
|
2022-10-09 |
20.04 |
3.10 |
|
2022-10-09 |
22.04 |
3.7 |
|
2022-10-09 |
22.04 |
3.8 |
|
2022-10-09 |
22.04 |
3.9 |
|
2023-05-30 |
22.04 |
3.10 |
|
weekly build |
22.04 |
3.11 |
|
Contributing#
Please see the Contributor Guide on ReadTheDocs for information about how to contribute recipes, features, tests, and community-maintained stacks.
Alternatives#
rocker/binder - From the R focused rocker-project, lets you run both RStudio and Jupyter either standalone or in a JupyterHub
jupyter/repo2docker - Turn git repositories into Jupyter-enabled Docker Images
openshift/source-to-image - A tool for building artifacts from source code and injecting them into docker images
jupyter-on-openshift/jupyter-notebooks - OpenShift compatible S2I builder for basic notebook images
Table of Contents#
- Selecting an Image
- Running a Container
- Common Features
- Image Specifics
- Contributed Recipes
- Using
sudo
within a container - Using
mamba install
(recommended) orpip install
in a Child Docker image - Add a custom conda environment and Jupyter kernel
- Dask JupyterLab Extension
- Let’s Encrypt a Server
- Slideshows with JupyterLab and RISE
- xgboost
- Running behind an nginx proxy
- Host volume mounts and notebook errors
- Manpage installation
- JupyterHub
- Spark
- Run Server inside an already secured environment (i.e., with no token)
- Enable nbclassic-extension spellchecker for markdown (or any other nbclassic-extension)
- Enable Delta Lake in Spark notebooks
- Add Custom Fonts in Scipy notebook
- Enable clipboard in pandas on Linux systems
- Add ijavascript kernel to container
- Add Microsoft SQL Server ODBC driver
- Add Oracle SQL Instant client, SQL*Plus, and other tools (Version 21.x)
- Using
- Troubleshooting Common Problems
- Frequently Asked Questions (FAQ)