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.
- multi-user Hub (tornado process)
- configurable http proxy (node-http-proxy)
- multiple single-user IPython notebook servers (Python/IPython/tornado)
- 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
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
nodejs-legacy package installs the
node executable and is currently
required for npm to work on Debian/Ubuntu.)
sudo npm install -g configurable-http-proxy
(Optional) Installation Prerequisite (pip)
Notes on the
pip command used in the installation directions below:
sudomay be needed for
pip install, depending on the user's filesystem permissions.
JupyterHub requires Python >= 3.3, so
pip3may 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
pip3is 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
For a development install, clone the repository and then install from source:
git clone https://github.com/jupyter/jupyterhub cd jupyterhub pip3 install -r dev-requirements.txt -e .
pip3 install command fails and complains about
python3 setup.py js # fetch updated client-side js (changes rarely) python3 setup.py 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
jupyterhub command as a privileged user, such as root.
describes how to run the server as a less privileged user, which requires more
configuration of the system.
See the getting started document for the
basics of configuring your JupyterHub deployment.
Generate a default config file:
Spawn the server on
10.0.1.2:443 with https:
jupyterhub --ip 10.0.1.2 --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:
- Using GitHub OAuth instead of PAM with OAuthenticator
- Spawning single-user servers with Docker, using the DockerSpawner
We encourage you to ask questions on the mailing list:
and you may participate in development discussions or get live help on Gitter: