See the CUDA-enabled JupyterLab Python docker stack for GPU accelerated docker images.

JupyterLab Python docker stack

Multi-arch (linux/amd64, linux/arm64/v8) docker images:

• glcr.b-data.ch/jupyterlab/python/base
• glcr.b-data.ch/jupyterlab/python/scipy

Images considered stable for Python versions ≥ 3.10.5.

🔬 Check out jupyterlab/python/scipy at https://demo.jupyter.b-data.ch.

Build chain

base → scipy

Features

• JupyterLab: A web-based interactive development environment for Jupyter notebooks, code, and data. The images include
  • code-server: Code - OSS in the browser.
  • Git: A distributed version-control system for tracking changes in source code.
  • Git LFS: A Git extension for versioning large files.
  • Pandoc: A universal markup converter.
  • Python: An interpreted, object-oriented, high-level programming language with dynamic semantics.
  • Quarto: A scientific and technical publishing system built on Pandoc.
    ℹ️ scipy image
  • TinyTeX: A lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live.
    ℹ️ scipy image
  • Zsh: A shell designed for interactive use, although it is also a powerful scripting language.

👉 See the Version Matrix for detailed information.

The following extensions are pre-installed for code-server:

• .gitignore Generator
• Black Formatter
  ℹ️ devtools subtags
• Docker
  ℹ️ docker subtags
• EditorConfig (3.11.3+)
• ESLint
  ℹ️ devtools subtags
• Git Graph
• GitHub Pull Requests and Issues (3.11.5+)
• GitLab Workflow
• GitLens — Git supercharged
  ℹ️ Pinned to version 11.7.0 due to unsolicited AI content (3.11.4+)
• Excel Viewer
• hadolint
  ℹ️ docker subtags (3.11.4+)
• Jupyter
• LaTeX Workshop
  ℹ️ scipy image
• markdownlint (3.11.6+)
• Path Intellisense
• Prettier - Code formatter
  ℹ️ devtools subtags
• Project Manager
• Python
• Quarto
  ℹ️ scipy image
• Resource Monitor (3.11.4+)
• ShellCheck
  ℹ️ devtools and docker subtags (3.11.4+)
• YAML

Subtags

• {PYTHON_VERSION,latest}-root (versions ≥ 3.10.5): Container runs as root
• {PYTHON_VERSION,latest}-devtools (versions ≥ 3.10.5): Includes the requirements according to
  • coder/code-server > Docs > Contributing
  • microsoft/vscode-python > Wiki > Coding
• {PYTHON_VERSION,latest}-devtools-root: The combination of both
• {PYTHON_VERSION,latest}-docker (versions ≥ 3.10.11, versions ≥ 3.11.2): Includes
  • docker-ce-cli
  • docker-buildx-plugin
  • docker-compose-plugin
  • docker-scan-plugin (amd64 only)
• {PYTHON_VERSION,latest}-docker-root: The combination of both
• {PYTHON_VERSION,latest}-devtools-docker: The combination of both
• {PYTHON_VERSION,latest}-devtools-docker-root: The combination of all three

Table of Contents

• Prerequisites
• Install
• Usage
• Similar projects
• Contributing
• Support
• License

Prerequisites

This projects requires an installation of docker.

Install

To install docker, follow the instructions for your platform:

• Install Docker Engine | Docker Documentation > Supported platforms
• Post-installation steps for Linux

Usage

Build image (base)

latest:

cd base && docker build \
  --build-arg PYTHON_VERSION=3.12.3 \
  -t jupyterlab/python/base \
  -f latest.Dockerfile .

version:

cd base && docker build \
  -t jupyterlab/python/base:MAJOR.MINOR.PATCH \
  -f MAJOR.MINOR.PATCH.Dockerfile .

For MAJOR.MINOR.PATCH ≥ 3.10.5.

Create home directory

Create an empty directory using docker:

docker run --rm \
  -v "${PWD}/jupyterlab-jovyan":/dummy \
  alpine chown 1000:100 /dummy

It will be bind mounted as the JupyterLab user's home directory and automatically populated.
❗ Bind mounting a subfolder of the home directory is only possible for images with Python version ≥ 3.12.2.

Run container

self built:

docker run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  jupyterlab/python/base[:MAJOR.MINOR.PATCH]

from the project's GitLab Container Registries:

docker run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

IMAGE being one of

• glcr.b-data.ch/jupyterlab/python/base
• glcr.b-data.ch/jupyterlab/python/scipy

The use of the -v flag in the command mounts the empty directory on the host (${PWD}/jupyterlab-jovyan in the command) as /home/jovyan in the container.

-e NB_UID=$(id -u) -e NB_GID=$(id -g) instructs the startup script to switch the user ID and the primary group ID of ${NB_USER} to the user and group ID of the one executing the command.

-e CHOWN_HOME=yes -e CHOWN_HOME_OPTS='-R' instructs the startup script to recursively change the ${NB_USER} home directory owner and group to the current value of ${NB_UID} and ${NB_GID}.
ℹ️ This is only required for the first run.

The server logs appear in the terminal.

Using Podman (rootless mode, 3.11.6+)

Create an empty home directory:

mkdir "${PWD}/jupyterlab-root"

Use the following command to run the container as root:

podman run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-root":/home/root \
  -e NB_USER=root \
  -e NB_UID=0 \
  -e NB_GID=0 \
  -e NOTEBOOK_ARGS="--allow-root" \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

Using Docker Desktop

Creating a home directory might not be required. Also

docker run -it --rm \
  -p 8888:8888 \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

might be sufficient.

Credential storage

❗ Keyring services are not available due to the difficulties of setting them up in containers.
Therefore, provide login credentials for the following extensions as environment variables (-e):

Extension	Environment variable
GitHub Pull Requests and Issues	GITHUB_TOKEN: Personal access token with scopes repo and user.1
GitLab Workflow	GITLAB_WORKFLOW_INSTANCE_URL: GitLab instance URL (e.g. https://gitlab.com). GITLAB_WORKFLOW_TOKEN: Personal access token with scopes api and read_user.

Similar projects

• jupyter/docker-stacks
• geocompx/docker

What makes this project different:

1. Multi-arch: linux/amd64, linux/arm64/v8
   ℹ️ Runs on Apple M series using Docker Desktop.
2. Base image: Debian instead of Ubuntu
   ℹ️ CUDA-enabled images are Ubuntu-based.
3. IDE: code-server next to JupyterLab
   ℹ️ code-server = Code - OSS in the browser.
4. Just Python – no Conda / Mamba

See Notes for tweaks, settings, etc.

Contributing

PRs accepted. Please submit to the GitLab repository.

This project follows the Contributor Covenant Code of Conduct.

Support

For commercial support, please contact b-data by email: support@b-data.ch.

b-data tailors the JupyterLab images to your needs, e.g.

• Integration of self-signed CA certificates to enable communication with web services on the intranet.
• Setting up the necessary environment variables so that everything works behind a corporate proxy server.

Additionally, the JupyterHub setup can be customised to allow

• authentication with AD/LDAP
• mounting CIFS/SMB file shares

and much more.

License

Copyright © 2022 b-data GmbH

Distributed under the terms of the MIT License, with exceptions.

Footnotes

1. Device activation may require a one-time login from the extension's sidebar. ↩