Quickstart

Prerequisites

Before installing JupyterHub, you will need:

• a Linux/Unix based system

• Python 3.5 or greater. An understanding of using pip or conda for installing Python packages is helpful.

• nodejs/npm. Install nodejs/npm, using your operating system’s package manager.

  • If you are using conda, the nodejs and npm dependencies will be installed for you by conda.

  • If you are using pip, install a recent version of nodejs/npm. For example, install it 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.

• A pluggable authentication module (PAM) to use the default Authenticator. PAM is often available by default on most distributions, if this is not the case it can be installed by using the operating system’s package manager.

• TLS certificate and key for HTTPS communication

• Domain name

Before running the single-user notebook servers (which may be on the same system as the Hub or not), you will need:

• Jupyter Notebook version 4 or greater

Installation

JupyterHub can be installed with pip (and the proxy with npm) or conda:

pip, npm:

python3 -m pip install jupyterhub
npm install -g configurable-http-proxy
python3 -m pip install notebook  # needed if running the notebook servers locally

conda (one command installs jupyterhub and proxy):

conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
conda install notebook  # needed if running the notebook servers locally

Test your installation. If installed, these commands should return the packages’ help contents:

jupyterhub -h
configurable-http-proxy -h

Start the Hub server

To start the Hub server, run the command:

jupyterhub

Visit https://localhost:8000 in your browser, and sign in with your unix credentials.

To allow multiple users to sign in to the Hub server, you must start jupyterhub as a privileged user, such as root:

sudo jupyterhub

The wiki describes how to run the server as a less privileged user. This requires additional configuration of the system.

Installation Using Docker