mirror of
https://github.com/jupyter/docker-stacks.git
synced 2025-10-07 01:54:04 +00:00
185 lines
10 KiB
Markdown
185 lines
10 KiB
Markdown
# Jupyter Docker Stacks
|
||
|
||
[](https://github.com/jupyter/docker-stacks/actions/workflows/docker.yml?query=branch%3Amain "Docker images build status")
|
||
[](https://jupyter-docker-stacks.readthedocs.io/en/latest/ "Documentation build status")
|
||
[](https://results.pre-commit.ci/latest/github/jupyter/docker-stacks/main "pre-commit.ci build status")
|
||
[](https://discourse.jupyter.org/ "Jupyter Discourse Forum")
|
||
[](https://mybinder.org/v2/gh/jupyter/docker-stacks/main?urlpath=lab/tree/README.ipynb "Launch a quay.io/jupyter/base-notebook container on mybinder.org")
|
||
|
||
Jupyter Docker Stacks are a set of ready-to-run [Docker images](https://quay.io/organization/jupyter) 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 the quay.io/jupyter/base-notebook image](https://mybinder.org/v2/gh/jupyter/docker-stacks/main?urlpath=lab/tree/README.ipynb) on <https://mybinder.org>.
|
||
Otherwise, the examples below may help you get started if you [have Docker installed](https://docs.docker.com/get-started/get-docker/),
|
||
know [which Docker image](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html) you want to use, and want to launch a single Jupyter Application in a container.
|
||
|
||
The [User Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/en/latest/) 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 `2025-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:
|
||
|
||
```bash
|
||
docker run -p 10000:8888 quay.io/jupyter/scipy-notebook:2025-03-14
|
||
```
|
||
|
||
You can modify the port on which the container's port is exposed by [changing the value of the `-p` option](https://docs.docker.com/engine/containers/run/#exposed-ports) 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 `2025-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.
|
||
|
||
```bash
|
||
docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work quay.io/jupyter/datascience-notebook:2025-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](https://docs.docker.com/reference/cli/docker/container/run/#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 `-i` flag](https://docs.docker.com/reference/cli/docker/container/run/#interactive) keeps the container's `STDIN` open, and lets you send input to the container through standard input.
|
||
[The `-t` flag](https://docs.docker.com/reference/cli/docker/container/run/#tty) attaches a pseudo-TTY to the container.
|
||
|
||
```{note}
|
||
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](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#alternative-commands).
|
||
|
||
## Resources
|
||
|
||
- [Documentation on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/en/latest/)
|
||
- [Issue Tracker on GitHub](https://github.com/jupyter/docker-stacks/issues)
|
||
- [Jupyter Discourse Forum](https://discourse.jupyter.org/)
|
||
- [Jupyter Website](https://jupyter.org)
|
||
- [Images on Quay.io](https://quay.io/organization/jupyter)
|
||
|
||
## Acknowledgments
|
||
|
||
- Starting from `2022-07-05`, `aarch64` self-hosted runners were sponsored by [`@mathbunnyru`](https://github.com/mathbunnyru/).
|
||
Please, consider [sponsoring his work](https://github.com/sponsors/mathbunnyru) on GitHub
|
||
- Starting from `2023-10-31`, `aarch64` self-hosted runners are sponsored by an amazing [`2i2c non-profit organization`](https://2i2c.org)
|
||
- Starting from `2025-02-11`, we use GitHub-hosted `aarch64` runners
|
||
|
||
## 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
|
||
|
||
[](https://www.python.org/downloads/ "Python versions supported")
|
||
|
||
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` |
|
||
| 2025-08-11 | 24.04 | 3.12 | `82d322f00937` |
|
||
| weekly build | 24.04 | 3.13 | `latest` |
|
||
|
||
## Contributing
|
||
|
||
Please see the [Contributor Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/en/latest/)
|
||
for information about how to contribute recipes, features, tests, and community-maintained stacks.
|
||
|
||
## LICENSE
|
||
|
||
This project is licensed under the terms of the Modified BSD License (also known as New or Revised or 3-Clause BSD).
|
||
|
||
## About the Jupyter Development Team
|
||
|
||
The Jupyter Development Team is the set of all contributors to the Jupyter project.
|
||
This includes all of the Jupyter subprojects.
|
||
|
||
The core team that coordinates development on GitHub can be found here:
|
||
<https://github.com/jupyter/>.
|
||
|
||
## Our Copyright Policy
|
||
|
||
Jupyter uses a shared copyright model. Each contributor maintains copyright
|
||
over their contributions to Jupyter. But, it is important to note that these
|
||
contributions are typically only changes to the repositories. Thus, the Jupyter
|
||
source code, in its entirety is not the copyright of any single person or
|
||
institution. Instead, it is the collective copyright of the entire Jupyter
|
||
Development Team. If individual contributors want to maintain a record of what
|
||
changes/contributions they have specific copyright on, they should indicate
|
||
their copyright in the commit message of the change, when they commit the
|
||
change to one of the Jupyter repositories.
|
||
|
||
With this in mind, the following banner should be used in any source code file
|
||
to indicate the copyright and license terms:
|
||
|
||
```text
|
||
# Copyright (c) Jupyter Development Team.
|
||
# Distributed under the terms of the Modified BSD License.
|
||
```
|
||
|
||
## Alternatives
|
||
|
||
- [b-data](https://github.com/b-data)'s JupyterLab docker stacks - For
|
||
[R](https://github.com/b-data/jupyterlab-r-docker-stack),
|
||
[Python](https://github.com/b-data/jupyterlab-python-docker-stack),
|
||
[MAX/Mojo](https://github.com/b-data/jupyterlab-mojo-docker-stack) and
|
||
[Julia](https://github.com/b-data/jupyterlab-julia-docker-stack).
|
||
With [code-server](https://github.com/coder/code-server) next to JupyterLab.
|
||
Just Python – no [Conda](https://github.com/conda/conda) /
|
||
[Mamba](https://github.com/mamba-org/mamba).
|
||
- [rocker/binder](https://rocker-project.org/images/versioned/binder.html) -
|
||
From the R focused [rocker-project](https://rocker-project.org),
|
||
lets you run both RStudio and Jupyter either standalone or in a JupyterHub
|
||
- [jupyter/repo2docker](https://github.com/jupyterhub/repo2docker) -
|
||
Turn git repositories into Jupyter-enabled Docker Images
|
||
- [openshift/source-to-image](https://github.com/openshift/source-to-image) -
|
||
A tool for building artifacts from source code and injecting them into docker images
|
||
- [jupyter-on-openshift/jupyter-notebooks](https://github.com/jupyter-on-openshift/jupyter-notebooks) -
|
||
OpenShift compatible S2I builder for basic notebook images
|