Skip to content

Rescue Mode

Overview

“Rescue Mode” launches a minimally configured JupyterLab image that uses a temporary home directory (/rescue-home). The original home directory is mounted at

/rescue-home/original-home

so that you can read from and write to it without starting the regular environment.

When is Rescue Mode useful?

Rescue Mode can help if JupyterLab fails to start, for example due to: - a full Home directory. - corrupted packages installed by mistake (e.g., in .local). - shell configuration files that have been modified or are faulty (e.g., .bashrc). - a corrupted user environment caused by incompatible extensions or software.

Rescue Mode can be used to delete or repair files in the original Home directory without launching a regular JupyterLab environment.

What Happens in Rescue Mode?

When Rescue Mode starts

  • A temporary, clean Home directory (/rescue-home) is created.
  • the original Home directory is mounted at /rescue-home/original-home,
  • A JupyterLab session is launched with a minimal environment, without any extensions or user settings.

This allows you to safely view, edit, or delete files in the original home directory.

Typical Use Cases

  • Cleaning up the home directory.
  • Deleting corrupted files/folders.
  • Removing or renaming packages in the ~/.local/lib/pythonX.Y/site-packages directory.
  • Resetting .bashrc, .profile, or the entire .jupyter directory.
  • Copying important data from the original-home directory to a secure folder within /rescue-home.

How to Fix a Broken Environment

  1. Check the Log Viewer – After clicking "Start" on the spawn page to start the server, open the "Logs" link on the subsequent page and look for error messages. (e.g., a reference to a package in the home directory). The JupyterLab environment is supposed to obtain its own packages exclusively from the image; packages in the home directory can cause issues here.
  2. Stop the server (if the server is running) – In the Hub menu, click Home > Stop My Server.
  3. Start Rescue Mode – In the Hub menu, click Home > Start My Server. Select “Rescue Mode” and click “Start”.
  4. Open original-home – In the file browser on the left, open the original-home/ folder.
  5. Remove/rename problematic files – These files can cause issues due to the installation of incompatible packages in the user environment (home directory). For example: 
    rm -rf ~/original-home/.local/lib/python3.12/site-packages/defective_package
    A typical example is a jupyterlab package installed in the home directory – this is almost always incorrect and must be removed (if necessary, all files/folders starting with jupyterlab). Make sure to check the correct Python version installed in the JupyterLab environment. Occasionally, it is necessary to delete the entire contents of site-packages to ensure a clean environment.
  6. If the problem persists, back up the .bashrc file or the .jupyter folder. For example: 
    mv original-home/.bashrc original-home/.bashrc.bak
    Note: To display hidden files in the file browser, select View > Show Hidden Files from the menu.
  7. Restart the server – In the Hub menu: Select File > Hub Control Panel > Stop My Server, then Start My Server.