How to Use the “Other” Image Option in JupyterHub

The “Other” image option in JupyterHub lets you run a custom computing environment, including your preferred libraries, packages, and tools by using a Docker image hosted on a public registry.

Prerequisites: Make Your Image JupyterHub-Compatible¶

To work with Nautilus JupyterHub (which uses DockerSpawner), your image must:

• Use Python 3.12+

• Include the notebook package

• Match the JupyterHub version (e.g., 4.x for Nautilus)

• Either:

  • Include a CMD that runs jupyterhub-singleuser, or

  • Let DockerSpawner override the command at runtime

Example: Building a Custom Image Based on Jupyter’s Base¶

You can start from a trusted Jupyter base image like scipy-notebook, and layer your own libraries on top.

Example Dockerfile:

FROM quay.io/jupyter/scipy-notebook:2023-10-23
ARG JUPYTERHUB_VERSION=4.3.5

RUN pip3 install --no-cache \
    jupyterhub==$JUPYTERHUB_VERSION

This base image already includes a working entrypoint that launches the notebook server.

Build and Push Your Image¶

Follow the official Docker guide to push your image to a registry like Docker Hub.

1. Login to your registry

$ docker login

2. Build and tag your image

$ docker build -t jhub-student:1.0 .

3. Push to Docker Hub

$ docker push jhub-student:1.0

4. Verify (optional)

$ docker pull docker.io/yourusername/jhub-student:1.0

Supported Docker Image URL Formats¶

You’ll need to paste your image’s full URL into the “Other” image field in the JupyterHub Server Options.

Here are valid formats:

• jhub-student

• jhub-student:1.0

• docker.io/yourusername/jhub-student:1.0

• ghcr.io/yourorg/jhub-custom:latest

Create a Server with a Custom Image¶

1. Go to the Create Server page

2. Adjust any hardware resources (CPUs, RAM, GPUs) as needed

3. Click the dropdown under “Notebook Container Image”

4. Select “Other” from the list

5. Paste your Docker image URL (e.g., docker.io/yourusername/jhub-student:1.0)

6. Click “Start Server”

Your custom environment will launch in JupyterHub using the Docker image you provided.