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.

  • 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:

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.