Skip to content

Rescue Mode

JupyterHub Rescue mode Image Documentation

Overview

The rescue mode image is a special-purpose container image designed to help users recover from broken environments that prevent their standard JupyterLab sessions from starting correctly.

This image launches a minimal JupyterLab environment with a temporary, clean $HOME directory (/rescue-home) and provides read/write access to the original home directory via a mounted path (/rescue-home/original-home).

When Should You Use the Rescue Image?

Use the rescue mode image when:

  • JupyterLab fails to start due to:
  • You accidentally installed a broken package (e.g., in .local)
  • You edited or corrupted shell configuration files (e.g., .bashrc)
  • Your user environment is broken due to incompatible extensions or software
  • You want to safely delete or fix files in your original home without interfering with a full JupyterLab session.

What Does the Rescue Mode Image Do?

  • Creates a temporary, clean $HOME at /rescue-home
  • Mounts your original home directory to /rescue-home/original-home
  • Starts a minimal JupyterLab session (no extensions or user settings loaded)
  • Lets you safely view, modify, or delete files in your real home

What You Can Do in Rescue Image

  • View and delete broken files
  • Remove or rename corrupt packages in .local/
  • Reset or move .bashrc, .profile, or .jupyter folders
  • Confirm what’s in your original home directory
  • Copy files from your original home to rescue-safe space

How to Fix a Broken Environment

  1. Start the Rescue mode image from the image dropdown.
  2. Navigate to original-home/.
  3. Identify and fix/remove problematic content:
  4. e.g., rm -rf ~/original-home/.local/lib/python3.12/site-packages/broken_package. A brocken package could be, for example, jupyterlab and you might have to remove every file and folder starting with jupyterlab. Please also pay attention to the python version as well and replace it with the version already installed in the jupyterlab einvironment. Sometimes you have to remove everything under site-packages so that your environment become clean.
  5. e.g., mv original-home/.bashrc original-home/.bashrc.bak
  6. Log out and re-launch your regular JupyterLab image.

Note: If you want to see the hidden files in the browser, you can activate it via the menu: view/Show Hidden Files