Public | Automated Build

Last pushed: 2 years ago
Short Description
Full Description

JupyterHub: A multi-user server for Jupyter notebooks

Questions, comments? Visit our Google Group:

JupyterHub, a multi-user server, manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.

Three actors:

  • multi-user Hub (tornado process)
  • configurable http proxy (node-http-proxy)
  • multiple single-user IPython notebook servers (Python/IPython/tornado)

Basic principles:

  • Hub spawns proxy
  • Proxy forwards ~all requests to hub by default
  • Hub handles login, and spawns single-user servers on demand
  • Hub configures proxy to forward url prefixes to single-user servers


JupyterHub itself requires Python ≥ 3.3. To run the single-user servers (which may be on the same system as the Hub or not), Jupyter Notebook ≥ 4 is required.

Install nodejs/npm, which is available from your
package manager. For example, install on Linux (Debian/Ubuntu) using:

sudo apt-get install npm nodejs-legacy

(The nodejs-legacy package installs the node executable and is currently
required for npm to work on Debian/Ubuntu.)

Next, install JavaScript dependencies:

sudo npm install -g configurable-http-proxy

(Optional) Installation Prerequisite (pip)

Notes on the pip command used in the installation directions below:

  • sudo may be needed for pip install, depending on the user's filesystem permissions.
  • JupyterHub requires Python >= 3.3, so pip3 may be required on some machines for package installation instead of pip (especially when both Python 2 and Python 3 are installed on a machine). If pip3 is not found, install it using (on Linux Debian/Ubuntu):

      sudo apt-get install python3-pip


JupyterHub can be installed with pip, and the proxy with npm:

npm install -g configurable-http-proxy
pip3 install jupyterhub

If you plan to run notebook servers locally, you may also need to install the
Jupyter IPython notebook:

pip3 install --upgrade notebook

Development install

For a development install, clone the repository and then install from source:

git clone
cd jupyterhub
pip3 install -r dev-requirements.txt -e .

If the pip3 install command fails and complains about lessc being unavailable, you may need to explicitly install some additional JavaScript dependencies:

npm install

This will fetch client-side JavaScript dependencies necessary to compile CSS.

You may also need to manually update JavaScript and CSS after some development updates, with:

python3 js    # fetch updated client-side js (changes rarely)
python3 css   # recompile CSS from LESS sources

Running the server

To start the server, run the command:


and then visit http://localhost:8000, and sign in with your unix credentials.

To allow multiple users to sign into the server, you will need to
run the jupyterhub command as a privileged user, such as root.
The wiki
describes how to run the server as a less privileged user, which requires more
configuration of the system.

Getting started

See the getting started document for the
basics of configuring your JupyterHub deployment.

Some examples

Generate a default config file:

jupyterhub --generate-config

Spawn the server on with https:

jupyterhub --ip --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert

The authentication and process spawning mechanisms can be replaced,
which should allow plugging into a variety of authentication or process control environments.
Some examples, meant as illustration and testing of this concept:

Getting help

We encourage you to ask questions on the mailing list:

and you may participate in development discussions or get live help on Gitter:


Docker Pull Command
Source Repository