Written and maintained by CASRAI Editorial Board
Last updated
JupyterHub is the Jupyter project’s multi-user server: it starts, manages and proxies a separate Jupyter notebook server for each user, so a class, a research group or a data-science team can share one machine or cluster instead of each installing Python locally. This guide is for a lab, course or research-computing lead who needs to decide which JupyterHub distribution fits and then get a first login working. Facts below were read from the official JupyterHub and Littlest JupyterHub documentation on 2026-11-07.
What JupyterHub is used for in research
The JupyterHub documentation describes it as a way to serve Jupyter notebooks for multiple users, and names three typical groups: a class of students, a corporate data science group, or a scientific research group. In a research setting that means one managed, central environment where each person gets their own notebook server, which supports a shared computational environment and makes it easier to rerun analyses, a building block of computational reproducibility.
JupyterHub vs JupyterLab and Jupyter Notebook
They are different layers. JupyterLab and Jupyter Notebook are the interfaces a single user works in. JupyterHub sits above them: it authenticates users and launches one single-user notebook server per person. The quickstart notes that the single-user servers need JupyterLab 3 or newer, or Notebook 4 or newer, installed alongside the Hub. If you only need notebooks for yourself, see Google Colab vs Jupyter Notebook and installing Anaconda Python.
How the pieces fit
According to the documentation, JupyterHub has four subsystems: the Hub (a tornado process, described as the heart of the system), a configurable HTTP proxy, the single-user notebook servers that Spawners start and monitor, and an authentication class that controls who may sign in.
Which distribution to use
The documentation offers two ready-made distributions in addition to installing the pieces yourself. Choose by the number of users and where the Hub will run.
| Option | Intended scale and setting (per docs) | Requirements stated in docs |
|---|---|---|
| The Littlest JupyterHub (TLJH) | Roughly 1 to 100 users on a single server | Root access and SSH to the server, at least 1 GB RAM, a public IP address; not for laptops; running inside Docker is not supported |
| Zero to JupyterHub with Kubernetes (Z2JH) | Cloud deployments for larger user counts | Runs on Kubernetes |
| Manual install with pip or conda | Building the Hub yourself, starting from the quickstart | Linux or Unix system, Python 3.10 or newer, Node.js 12 or newer with npm, PAM for the default authenticator |
Install or access (official source only)
Prerequisites for the manual install
The quickstart lists: a Linux or Unix system; Python 3.10 or newer; Node.js 12 or newer with npm (a conda install supplies these); PAM for the default authenticator; and, for HTTPS, a TLS certificate and key plus a domain name.
Install with pip
python3 -m pip install jupyterhub npm install -g configurable-http-proxy python3 -m pip install jupyterlab notebookInstall with conda
conda install -c conda-forge jupyterhub conda install jupyterlab notebookVerify the install
jupyterhub -h configurable-http-proxy -hBoth commands should print their help text. If either is not found, the corresponding install step did not complete.
Step-by-step: from install to first login
Manual install, following the quickstart
- Install JupyterHub, the proxy, and JupyterLab and Notebook with the commands above, and verify both commands.
- Create a file named
jupyterhub_config.pycontainingc = get_config() # noqaandc.Authenticator.allow_all = True. To restrict access instead, the quickstart’s alternative isc.Authenticator.allowed_users = {"yourusername"}. - Start the Hub with
jupyterhub. - Open
http://localhost:8000and sign in with your Unix credentials, which the default PAM authenticator checks.
Signing in as several different users requires starting the Hub as a privileged user, for example sudo jupyterhub. The documentation covers running without root privileges in a separate guide on using sudo.
The Littlest JupyterHub on a server
- On a server where you have root and SSH access, install prerequisites:
sudo apt install python3 python3-dev git curl - Run the bootstrap script, replacing the placeholder with the account that will be administrator:
curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>. The documentation says this takes 5 to 10 minutes and ends with “Done!”. - Open
http://<public-ip>in a browser, log in as the admin user and choose a password. - Add users and grant admin rights from the Hub Control Panel, on the Admin page.
Output and how to read it
A working manual install shows the Hub’s login page at http://localhost:8000; after sign-in, the user lands in their own notebook server. In a TLJH install, the Admin page in the Hub Control Panel is where you manage the user list. The jupyterhub -h and configurable-http-proxy -h checks confirm that the Hub and its proxy are available before you start the service.
Troubleshooting
- Only one user can sign in. The quickstart states that multi-user sign-in requires starting the Hub as a privileged user, such as
sudo jupyterhub. - Which credentials to use. The default authenticator uses PAM, so sign-in uses the Unix account on that machine.
- The TLJH bootstrap does not suit a laptop or a container. The TLJH documentation says it needs a server with root and SSH access, at least 1 GB RAM and a public IP, and that running inside Docker is not supported.
- Users cannot start their notebooks. The single-user servers need JupyterLab 3 or newer, or Notebook 4 or newer, installed.
Free alternatives
If running your own Hub is more than a project needs, the Jupyter project’s documentation describes two free options. Neither replaces a Hub for a group that needs its own accounts and persistent storage.
| Option | What the docs say | Source |
|---|---|---|
| mybinder.org (public BinderHub) | BinderHub is an open-source tool that runs on Kubernetes; the mybinder.org deployment is free to use. | mybinder.readthedocs.io |
| The Littlest JupyterHub | Free to install on your own server for roughly 1 to 100 users. | tljh.jupyter.org |
FAQ
What is JupyterHub used for?
Serving Jupyter notebooks to multiple users from shared infrastructure, with a separate notebook server per user. The documentation names classes, data-science groups and research groups as typical users.
Is JupyterHub the same as JupyterLab?
No. JupyterLab is a single-user interface; JupyterHub manages many users and starts a notebook server for each one.
How many users can the Littlest JupyterHub support?
The documentation positions it for roughly 1 to 100 users on a single server; for larger cloud deployments it points to Zero to JupyterHub with Kubernetes.
Where does the Hub run by default?
A manual install started with jupyterhub is reached at http://localhost:8000 by default.
For another research-data platform that sits alongside computational tools, see CUAHSI HydroShare.
Sources
- JupyterHub documentation home: jupyterhub.readthedocs.io/en/stable/index.html (read 2026-11-07)
- JupyterHub quickstart: jupyterhub.readthedocs.io/en/stable/tutorial/quickstart.html (read 2026-11-07)
- The Littlest JupyterHub, install on your own server: tljh.jupyter.org/en/latest/install/custom-server.html (read 2026-11-07)
- Binder documentation: mybinder.readthedocs.io/en/latest/ (read 2026-11-07)
