JupyterHub

Common errors

• User 'my-username' not allowed (403 Forbidden)

  cause By default, JupyterHub does not allow any users unless explicitly configured. This changed from older versions where `allow_all` might have been the default.
  fix Add the user to `c.Authenticator.allowed_users` in `jupyterhub_config.py`, or set `c.Authenticator.allow_all = True` (if using a basic authenticator that supports it).

• 500: Internal Server Error after spawning my single-user server

  cause This often occurs when the single-user server cannot connect to the Hub's API to verify the user cookie, or an invalid token is being used. Common causes include networking configuration problems (firewalls, reverse proxies), or an invalid API token (e.g., after resetting the JupyterHub database).
  fix Check JupyterHub and single-user server logs for connectivity issues or token errors. Ensure proper network configuration (firewalls, reverse proxies). If the database was reset, user tokens may be invalid. Restarting the single-user server or the Hub might resolve token issues.

• JupyterHub proxy fails to start

  cause This can be caused by an old Node.js version, or an incorrect `c.JupyterHub.ip` configuration. Some Ubuntu/Debian versions ship with very old Node.js.
  fix Update Node.js/npm to a recent version (>=12). Try setting `c.JupyterHub.ip = ''` in `jupyterhub_config.py` or starting with `jupyterhub --ip=0.0.0.0`.

• Permission denied: $PREFIX/etc/jupyter/lab (or similar permission errors in shared environments)

  cause When Jupyter is run in shared environments (like a common Conda or virtual environment for all users), it prefers to load and *write* configuration to environment-wide paths, which may not be user-writable, leading to permission errors.
  fix Set `c.JupyterApp.answer_yes = True` in `jupyterhub_config.py` (or a similar global Jupyter config) to tell Jupyter to prefer user configuration paths (e.g., `~/.jupyter`) over environment paths. Alternatively, ensure that shared environments have appropriate permissions.

Warnings

• breaking JupyterHub follows Intended Effort Versioning (EffVer), where major version bumps (e.g., 3.x to 4.x, 4.x to 5.x) typically involve significant breaking changes, such as database schema migrations, increased minimum Python versions, and configuration changes. Always review the changelog and upgrade instructions carefully.
  Fix: Before upgrading a major version, consult the 'Upgrading JupyterHub' documentation and the relevant changelog. Back up your `jupyterhub.sqlite` database and `jupyterhub_config.py` file. Use `jupyterhub --upgrade-db` after package upgrade if database schema changes are required.
• breaking JupyterHub officially does not support Windows. While some spawners/authenticators might work, default behavior is not guaranteed, and bug reports for Windows are not accepted.
  Fix: For Windows environments, it is strongly recommended to run JupyterHub within a Docker container or a Linux virtual machine.
• gotcha By default, if no explicit `admin_users`, `allowed_users`, or `allowed_groups` are configured, JupyterHub will allow all users who can authenticate on the system (e.g., all Unix users with a password via PAM) to start a server.
  Fix: For security, explicitly define `c.Authenticator.admin_users` and `c.Authenticator.allowed_users` in your `jupyterhub_config.py` file, or implement a custom authenticator, to control who can access the Hub.
• gotcha Upgrading JupyterHub, especially with the default `configurable-http-proxy` managed by JupyterHub, will cause service disruption for users.
  Fix: Notify users in advance and schedule upgrades during off-peak hours to minimize disruption. If using an independent proxy, existing user servers will continue, but new logins/spawns will be affected.
• deprecated The `DummyAuthenticator`'s password option has been deprecated.
  Fix: Avoid using deprecated options. Consult the latest documentation and changelog for recommended authentication methods. For simple testing, `c.Authenticator.allow_all = True` or `c.Authenticator.allowed_users` are more current approaches.

Install

• pip install jupyterhub npm install -g configurable-http-proxy Pip and NPM
• conda install -c conda-forge jupyterhub Conda

Imports

• Config object (c)

  # In jupyterhub_config.py, configuration is set via the 'c' object
  c.JupyterHub.port = 8000
  c.Authenticator.admin_users = {'youradminuser'}
  c.Authenticator.allowed_users = {'user1', 'user2'}

  JupyterHub is primarily configured through a `jupyterhub_config.py` file, where settings are applied to a global `c` object (an instance of `traitlets.config.loader.Config`).
• Authenticator

  from jupyterhub.auth import Authenticator

  Used when implementing a custom authenticator plugin for JupyterHub.
• Spawner

  from jupyterhub.spawner import Spawner

  Used when implementing a custom spawner plugin for JupyterHub.

Quickstart

This quickstart guides you through generating a configuration file, modifying it to allow a user, and starting the JupyterHub server. By default, JupyterHub attempts to authenticate against local system users via PAM.

# 1. Generate a default configuration file:
jupyterhub --generate-config

# 2. Edit jupyterhub_config.py to allow users (or all authenticated users)
# (Replace 'your_username' with your actual system username)
# You might add something like:
# c.Authenticator.allowed_users = {'your_username'}
# c.Authenticator.admin_users = {'your_username'}
# If you want to allow any user who can authenticate on the system (Unix users):
# c.Authenticator.auto_authenticate = True

# 3. Start JupyterHub (requires root privileges by default, or specific configuration for non-root)
jupyterhub