Portainer Templates logo

Portainer Templates

JupyterLab JupyterLab

Container

DevelopmentTools

Python notebooks in the browser for poking at data and plotting it, with a terminal alongside. It's Jupyter's scipy-notebook image, so pandas, NumPy, matplotlib and scikit-learn come installed. Source: https://github.com/jupyter/docker-stacks

Source details

Repo: jupyter/docker-stacks
Stars: 8k
Forks: 3k
Language: Python
License: BSD-3-Clause
Updated: 6 days ago
Website: jupyter-docker-stacks.readthedocs.io/

Configuration

Type
Container
Platform
linux
Image
quay.io/jupyter/scipy-notebook:latest
Ports
8888:8888/tcp
Volumes
/home/jovyan
Restart
unless-stopped

Template by NotAFlightRisk

Report issue

Notes

Open http://<your-host>:8888. It asks for a token, which is in the container's logs (the link ending /lab?token=...). Put that token and a new password into Setup a Password underneath, and you'll log in with the password from then on - otherwise the token changes on every restart. Whoever logs in gets a terminal inside the container, so keep it off the open internet unless it's behind HTTPS. Your notebooks, settings, password and anything you pip install --user live in the home folder volume. A plain pip install goes into the image and is gone after an update. Docs: jupyter-docker-stacks.readthedocs.io

Standalone Install

Select an install method, to see config/commands for deploying JupyterLab

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select JupyterLab, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

More install options in our documentation, or see jupyter/docker-stacks for app-specific guidance.

Jupyter Docker Stacks

GitHub Actions badge Read the Docs badge pre-commit.ci status Discourse badge Binder badge Code style: black OpenSSF Scorecard License 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 the quay.io/jupyter/base-notebook image on . 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 `2026-07-28` 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:2026-07-28

You can modify the host port to which the container's port is mapped 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 2026-07-28 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:2026-07-28

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 rootdir 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.13.14`
- 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
- Starting from `2025-12-02`, we create CUDA enabled variants of `pytorch-notebook` and `tensorflow-notebook` images for `aarch64` platform as well

## Using old images

[![Python versions badge](https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/ "Python versions supported")

This project only builds one set of images at a time.
The weekly build (`latest` tag) is based on `Ubuntu 26.04` and `Python 3.13`.
If you want to use the older `Ubuntu` and/or `Python` version, you can use the following images:

### Ubuntu 24.04


<table><thead><tr><th>Build Date</th><th>Python</th><th>Tag</th></tr></thead><tbody><tr><td>2024-10-22</td><td>3.11</td><td><code>b74418220768</code></td></tr><tr><td>2025-08-11</td><td>3.12</td><td><code>82d322f00937</code></td></tr><tr><td>2026-09-28</td><td>3.13</td><td><code>ac62373f9f60</code></td></tr></tbody></table>

### Ubuntu 22.04


<table><thead><tr><th>Build Date</th><th>Python</th><th>Tag</th></tr></thead><tbody><tr><td>2022-10-09</td><td>3.7</td><td><code>b86753318aa1</code></td></tr><tr><td>2022-10-09</td><td>3.8</td><td><code>7285848c0a11</code></td></tr><tr><td>2022-10-09</td><td>3.9</td><td><code>ed2908bbb62e</code></td></tr><tr><td>2023-05-30</td><td>3.10</td><td><code>4d70cf8da953</code></td></tr><tr><td>2024-08-26</td><td>3.11</td><td><code>00987883e58d</code></td></tr></tbody></table>

### Ubuntu 20.04


<table><thead><tr><th>Build Date</th><th>Python</th><th>Tag</th></tr></thead><tbody><tr><td>2022-10-09</td><td>3.7</td><td><code>1aac87eb7fa5</code></td></tr><tr><td>2022-10-09</td><td>3.8</td><td><code>a374cab4fcb6</code></td></tr><tr><td>2022-10-09</td><td>3.9</td><td><code>5ae537728c69</code></td></tr><tr><td>2022-10-09</td><td>3.10</td><td><code>f3079808ca8c</code></td></tr></tbody></table>

## Contributing

Please see the [the documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/)
for information about how to contribute
[issues](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/issues.html),
[features](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/features.html),
[recipes](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/recipes.html),
[tests](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/tests.html),
and [community-maintained stacks](https://jupyter-docker-stacks.readthedocs.io/en/latest/contributing/stacks.html).

## 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's JupyterLab docker stacks - For
R, Python, MAX/Mojo and Julia. With code-server next to JupyterLab. Just Python – no Conda / Mamba. From the R focused rocker-project, lets you run both RStudio and Jupyter either standalone or in a JupyterHub Turn git repositories into Jupyter-enabled Docker Images A tool for building artifacts from source code and injecting them into docker images OpenShift compatible S2I builder for basic notebook images

Serve JupyterLab on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying jupyterlab.example.com to http://jupyterlab:8888

Add this to your Caddyfile

jupyterlab.example.com {
	reverse_proxy http://jupyterlab:8888
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs jupyterlab
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:8888 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :8888
  • Stop the other service, or pick a different host port. In 8888:8888 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:8888. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, jupyterlab can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 8888

Image won't pull

Test the pull directly on the host: docker pull quay.io/jupyter/scipy-notebook:latest

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect jupyterlab --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A single container

JupyterLab runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything JupyterLab needs bundled into one download. This template pulls quay.io/jupyter/scipy-notebook:latest, which Docker fetches once and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. JupyterLab's comes from Quay, published by jupyter.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Pin a specific tag if you would rather stay on one version.

Ports

A port is the door the app answers on. A mapping like 8888:8888 means it's reachable on port 8888 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

  • 8888:8888

Volumes

A volume is where JupyterLab keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /home/jovyan as a volume Docker manages for you

Restart policy

The restart policy here is unless-stopped, so Docker restarts JupyterLab after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so JupyterLab sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container jupyterlab. That's what you'll spot in the containers list and use in commands like docker logs jupyterlab.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

JupyterLab is open source, released under the BSD-3-Clause license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set JupyterLab up. Add the template list to Portainer once, then deploying JupyterLab is a click rather than a wall of config.