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.6+
- Include the
notebook
package - Match the JupyterHub version (e.g., 4.x for Nautilus)
- Either:
- Include a
CMD
that runsjupyterhub-singleuser
, or - Let DockerSpawner override the command at runtime
- Include a
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.0.2
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.
Steps:
- Login to your registry
$ docker login
- Build and tag your image
$ docker build -t jhub-student:1.0 .
- Push to Docker Hub
$ docker push jhub-student:1.0
- 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.