Technical Overview | Installation | Configuration | Docker | Contributing | License | Help and Resources

JupyterHub

Latest PyPI version Latest conda-forge version Documentation build status GitHub Workflow Status - Test Test coverage of code GitHub Discourse Gitter

With JupyterHub you can create a multi-user Hub that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server.

Project Jupyter created JupyterHub to support many users. The Hub can offer notebook servers to a class of students, a corporate data science workgroup, a scientific research project, or a high-performance computing group.

Technical overview

Three main actors make up JupyterHub:

  • multi-user Hub (tornado process)
  • configurable http proxy (node-http-proxy)
  • multiple single-user Jupyter notebook servers (Python/Jupyter/tornado)

Basic principles for operation are:

  • Hub launches a proxy.
  • The 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 the single-user notebook servers.

JupyterHub also provides a REST API for administration of the Hub and its users.

Installation

Check prerequisites

  • A Linux/Unix based system

  • Python 3.8 or greater

  • nodejs/npm

    • 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 (at least 12.0) of nodejs/npm.

  • If using the default PAM Authenticator, a pluggable authentication module (PAM).

  • TLS certificate and key for HTTPS communication

  • Domain name

Install packages

Using conda

To install JupyterHub along with its dependencies including nodejs/npm:

conda install -c conda-forge jupyterhub

If you plan to run notebook servers locally, install JupyterLab or Jupyter notebook:

conda install jupyterlab
conda install notebook

Using pip

JupyterHub can be installed with pip, and the proxy with npm:

npm install -g configurable-http-proxy
python3 -m pip install jupyterhub

If you plan to run notebook servers locally, you will need to install JupyterLab or Jupyter notebook:

python3 -m pip install --upgrade jupyterlab
python3 -m pip install --upgrade notebook

Run the Hub server

To start the Hub server, run the command:

jupyterhub

Visit http://localhost:8000 in your browser, and sign in with your system username and password.

Note: To allow multiple users to sign in to the server, you will need to run the jupyterhub command as a privileged user, such as root. The documentation describes how to run the server as a less privileged user, which requires more configuration of the system.

Configuration

The Getting Started section of the documentation explains the common steps in setting up JupyterHub.

The JupyterHub tutorial provides an in-depth video and sample configurations of JupyterHub.

Create a configuration file

To generate a default config file with settings and descriptions:

jupyterhub --generate-config

Start the Hub

To start the Hub on a specific url and port 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

Authenticators

Authenticator Description
PAMAuthenticator Default, built-in authenticator
OAuthenticator OAuth + JupyterHub Authenticator = OAuthenticator
ldapauthenticator Simple LDAP Authenticator Plugin for JupyterHub
kerberosauthenticator Kerberos Authenticator Plugin for JupyterHub

Spawners

Spawner Description
LocalProcessSpawner Default, built-in spawner starts single-user servers as local processes
dockerspawner Spawn single-user servers in Docker containers
kubespawner Kubernetes spawner for JupyterHub
sudospawner Spawn single-user servers without being root
systemdspawner Spawn single-user notebook servers using systemd
batchspawner Designed for clusters using batch scheduling software
yarnspawner Spawn single-user notebook servers distributed on a Hadoop cluster
wrapspawner WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners

Docker

A starter docker image for JupyterHub gives a baseline deployment of JupyterHub using Docker.

Important: This quay.io/jupyterhub/jupyterhub image contains only the Hub itself, with no configuration. In general, one needs to make a derivative image, with at least a jupyterhub_config.py setting up an Authenticator and/or a Spawner. To run the single-user servers, which may be on the same system as the Hub or not, Jupyter Notebook version 4 or greater must be installed.

The JupyterHub docker image can be started with the following command:

docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub

This command will create a container named jupyterhub that you can stop and resume with docker stop/start.

The Hub service will be listening on all interfaces at port 8000, which makes this a good choice for testing JupyterHub on your desktop or laptop.

If you want to run docker on a computer that has a public IP then you should (as in MUST) secure it with ssl by adding ssl options to your docker configuration or by using an ssl enabled proxy.

Mounting volumes will allow you to store data outside the docker image (host system) so it will be persistent, even when you start a new image.

The command docker exec -it jupyterhub bash will spawn a root shell in your docker container. You can use the root shell to create system users in the container. These accounts will be used for authentication in JupyterHub's default configuration.

Contributing

If you would like to contribute to the project, please read our contributor documentation and the CONTRIBUTING.md. The CONTRIBUTING.md file explains how to set up a development installation, how to run the test suite, and how to contribute to documentation.

For a high-level view of the vision and next directions of the project, see the JupyterHub community roadmap.

A note about platform support

JupyterHub is supported on Linux/Unix based systems.

JupyterHub officially does not support Windows. You may be able to use JupyterHub on Windows if you use a Spawner and Authenticator that work on Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not be accepted, and the test suite will not run on Windows. Small patches that fix minor Windows compatibility issues (such as basic installation) may be accepted, however. For Windows-based systems, we would recommend running JupyterHub in a docker container or Linux VM.

Additional Reference: Tornado's documentation on Windows platform support

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

All code is licensed under the terms of the revised BSD license.

Help and resources

We encourage you to ask questions and share ideas on the Jupyter community forum. You can also talk with us on our JupyterHub Gitter channel.

JupyterHub follows the Jupyter Community Guides.

Technical Overview | Installation | Configuration | Docker | Contributing | License | Help and Resources

Project links

Data verified by PyPI on Sep 1, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (6.0.0)

Owner

PyPI data
Data sourced directly from PyPI's database.

6 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for betatim from gravatar.com betatim Avatar for choldgraf from gravatar.com choldgraf Avatar for consideRatio from gravatar.com consideRatio
+3 more Avatar for minrk from gravatar.com minrk Avatar for willingc from gravatar.com willingc Avatar for yuvipanda from gravatar.com yuvipanda

Credits

Author: Jupyter Development Team

GitHub Statistics

Data verified by PyPI on Sep 1, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD License (BSD-3-Clause)

Requires

Python >=3.8

Provides Extra

test

Tags

Interactive Interpreter Shell Web Jupyter

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyterhub-5.5.2.tar.gz (18.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

jupyterhub-5.5.2-py3-none-any.whl (14.2 MB view details)

Uploaded Python 3

File details

Details for the file jupyterhub-5.5.2.tar.gz.

File metadata

  • Download URL: jupyterhub-5.5.2.tar.gz
  • Upload date:
  • Size: 18.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for jupyterhub-5.5.2.tar.gz
Algorithm Hash digest
SHA256 e4860ac6b5d899f7b37a927f984d1fec0c5fbc196fe20bc4a75be9b7212510c2
MD5 e386c0c02868830e50d70f9b89c2db01
BLAKE2b-256 d1dbb8b2d3dccd665034a84e4d737f95be216eb9bbd4b5a50d55ff397d026fc7

See more details on using hashes here.

Provenance

The following attestation bundles were made for jupyterhub-5.5.2.tar.gz:

Publisher: release.yml on jupyterhub/jupyterhub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jupyterhub-5.5.2-py3-none-any.whl.

File metadata

  • Download URL: jupyterhub-5.5.2-py3-none-any.whl
  • Upload date:
  • Size: 14.2 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for jupyterhub-5.5.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f23b7116ea8202011be83dd895e971823b06428f7fa100c4e057f1e7e97d408e
MD5 598e53fc1cb357197dc9914c250a0d0b
BLAKE2b-256 37f023067e42cf89f4cf712de999a6b8816d0b8545303bec07499c2b86549090

See more details on using hashes here.

Provenance

The following attestation bundles were made for jupyterhub-5.5.2-py3-none-any.whl:

Publisher: release.yml on jupyterhub/jupyterhub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

6.0.0

2 files

Pre-release

6.0.0b3

2 files

Pre-release

6.0.0b2

2 files

Pre-release

6.0.0b1

2 files

This release

5.5.2 This release

2 files

5.5.1

2 files

5.5.0

2 files

5.4.6

2 files

5.4.5

2 files

5.4.4

2 files

5.4.3

2 files

5.4.2

2 files

5.4.1

2 files

5.4.0

2 files

5.3.0

2 files

Pre-release

5.3.0rc0

2 files

5.2.1

2 files

5.2.0

2 files

5.1.0

2 files

5.0.0

2 files

Pre-release

5.0.0b2

2 files

Pre-release

5.0.0b1

2 files

4.1.6

2 files

4.1.5

2 files

4.1.4

2 files

4.1.3

2 files

4.1.2

2 files

4.1.1

2 files

4.1.0

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

Pre-release

4.0.0b2

2 files

Pre-release

4.0.0b1

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

Pre-release

3.0.0b1

2 files

2.3.1

2 files

2.3.0

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.1

2 files

2.1.0

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

Pre-release

2.0.0rc5

2 files

Pre-release

2.0.0rc4

2 files

Pre-release

2.0.0rc3

2 files

Pre-release

2.0.0rc2

2 files

Pre-release

2.0.0rc1

2 files

Pre-release

2.0.0b3

2 files

Pre-release

2.0.0b2

2 files

Pre-release

2.0.0b1

2 files

1.5.1

2 files

1.5.0

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

Pre-release

1.2.0b1

2 files

1.1.0

2 files

Pre-release

1.1.0b1

2 files

1.0.0

2 files

Pre-release

1.0.0b2

2 files

Pre-release

1.0.0b1

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

Pre-release

0.9.0rc1

2 files

Pre-release

0.9.0b3

2 files

Pre-release

0.9.0b2

2 files

Pre-release

0.9.0b1

2 files

0.8.1

2 files

0.8.0

2 files

Pre-release

0.8.0rc2

2 files

Pre-release

0.8.0rc1

2 files

Pre-release

0.8.0b5

2 files

Pre-release

0.8.0b4

2 files

Pre-release

0.8.0b3

2 files

Pre-release

0.8.0b2

2 files

Pre-release

0.8.0b1

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

Pre-release

0.7.0b1

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

3 files

0.4.1

3 files

0.4.0

3 files

0.3.0

3 files

0.2.0

3 files

0.1.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page