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 by simply clicking the preceding link. 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 2023-11-17
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:2023-11-17
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 2023-11-17
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:2023-11-17
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 flag --rm
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 -it
flag allocates pseudo-TTY.
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.10.5
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 well
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#
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#
User Guide
- 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)
Contributor Guide
Maintainer Guide