Skip to content

Latest commit

 

History

History
140 lines (103 loc) · 8.37 KB

README.md

File metadata and controls

140 lines (103 loc) · 8.37 KB
Raw

Jupyter Docker Stacks

GitHub actions badge Read the Docs badge pre-commit.ci status Discourse badge Binder badge

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.

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-10-07 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-10-07

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 Docker
  • The 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-10-07 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-10-07

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.

By default, [jupyter's root_dir](https://jupyter-server.readthedocs.io/en/latest/other/full-config.html) 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

CPU Architectures

  • We publish containers for both x86_64 and aarch64 platforms
  • Single-platform images have either aarch64- or x86_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 (except tensorflow-notebook)
  • Starting from 2023-06-01, we create a multi-platform tensorflow-notebook image as well
  • Starting from 2024-02-24, we create CUDA enabled variants of pytorch-notebook image for x86_64 platform
  • Starting from 2024-03-26, we create CUDA enabled variant of tensorflow-notebook image for x86_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 1aac87eb7fa5
2022-10-09 20.04 3.8 a374cab4fcb6
2022-10-09 20.04 3.9 5ae537728c69
2022-10-09 20.04 3.10 f3079808ca8c
2022-10-09 22.04 3.7 b86753318aa1
2022-10-09 22.04 3.8 7285848c0a11
2022-10-09 22.04 3.9 ed2908bbb62e
2023-05-30 22.04 3.10 4d70cf8da953
2024-08-26 22.04 3.11 00987883e58d
2024-10-22 24.04 3.11 b74418220768
weekly build 24.04 3.12 latest

Contributing

Please see the Contributor Guide on ReadTheDocs for information about how to contribute recipes, features, tests, and community-maintained stacks.

Alternatives