Skip to content
Spawn JupyterHub single-user servers with sudo
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Replace debug_mediator with mediator_log_level Oct 26, 2018
sudospawner Replace debug_mediator with mediator_log_level Oct 26, 2018
.dockerignore add example Dockerfile Nov 26, 2014
.gitignore prep for release Feb 3, 2016 changelog for 0.5.2 Jun 19, 2018 Create Aug 4, 2017
LICENSE move example Dockerfile into examples Oct 10, 2017 update with long_description_content_type Jun 19, 2018



The SudoSpawner enables JupyterHub to spawn single-user servers without being root, by spawning an intermediate process via sudo, which takes actions on behalf of the user.

The sudospawner mediator, the intermediate process, can only do two things:

  1. send a signal to another process using the os.kill() call
  2. spawn single-user servers

Launching the sudospawner script is the only action that requires a JupyterHub administrator to have sudo access to execute.

Installation and setup

  1. Install:

     pip install -e .
  2. Add sudo access to the script.

  3. To configure JupyterHub to use SudoSpawner, add the following to your


    The JupyterHub documentation has additional information about creating a configuration file, if needed, and recommended file locations for configuration files.

Custom singleuser launch command

In order to limit what permissions the use of sudospawner grants the Hub, when a single-user server is launched the executable spawned is hardcoded as dirname(sudospawner)/jupyterhub-singleuser. This requires the sudospawner executable to be in the same directory as the jupyterhub-singleuser command. It is very important that users cannot modify the bin/ directory containing sudospawner, otherwise they can modify what sudospawner actually enables JupyterHub to do.

You may want to initialize user environment variables before launching the server, or do other initialization. If you install a script called sudospawner-singleuser next to sudospawner, this will be used instead of the direct jupyterhub-singleuser command.

For example, you might want to spawn notebook servers from conda environments that are revised and deployed separately from your hub instance.

#!/bin/bash -l
set -e

# Activate the notebook environment
source /opt/miniconda/bin/activate /opt/envs/notebook-latest

# Show environment info in the log to aid debugging
conda info

# Delegate the notebook server launch to the jupyterhub-singleuser script.
# this is how most sudospawner-singleuser scripts should end.
exec "$(dirname "$0")/jupyterhub-singleuser" $@

SudoSpawner with JupyterLab-Hub singleuser launch command

In order to have SudoSpawner work with JupyterLab-Hub you will need to create a custom singleuser launch command. Create the script sudospawner-singleuser containing the below code in the same directory as sudospawner and grant it the same permissions.

#!/bin/bash -l

# Delegate the notebook server launch to the jupyter-labhub script.
exec "jupyter-labhub" $@


The Dockerfile in this repo contains an example configuration for setting up a JupyterHub system, without any need to run anything as root.

You can’t perform that action at this time.