Quickstart#

Prerequisites#

Before installing JupyterHub, you will need:

a Linux/Unix based system
Python 3.6 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 nodejs npm
```
  nodesource is a great resource to get more recent versions of the nodejs runtime, if your system package manager only has an old version of Node.js (e.g. 10 or older).
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:

JupyterLab version 3 or greater, or Jupyter Notebook 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 jupyterlab notebook  # needed if running the notebook servers in the same environment

conda (one command installs jupyterhub and proxy):

conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
conda install jupyterlab notebook  # needed if running the notebook servers in the same environment

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 http://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.