{"id":7334,"library":"jupyterhub","title":"JupyterHub","description":"JupyterHub is a multi-user server for Jupyter notebooks, allowing groups of users to access computational environments and resources without individual installation and maintenance tasks. It is currently at version 5.4.4 and maintains a healthy release cadence, with at least one new version released every three months.","status":"active","version":"5.4.4","language":"en","source_language":"en","source_url":"https://github.com/jupyterhub/jupyterhub","tags":["jupyter","notebooks","multi-user","server","education","data-science","web-application"],"install":[{"cmd":"pip install jupyterhub\nnpm install -g configurable-http-proxy","lang":"bash","label":"Pip and NPM"},{"cmd":"conda install -c conda-forge jupyterhub","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"JupyterHub requires Python 3.8 or greater.","package":"python","optional":false},{"reason":"Node.js 12 or greater, along with npm, is required for the configurable-http-proxy, unless installed via conda which bundles it.","package":"nodejs","optional":false},{"reason":"A Node.js application that serves as the proxy for JupyterHub.","package":"configurable-http-proxy","optional":false},{"reason":"JupyterLab 3 or greater, or Jupyter Notebook 4 or greater, is needed to run the single-user notebook servers.","package":"jupyterlab","optional":true},{"reason":"Jupyter Notebook 4 or greater, or JupyterLab 3 or greater, is needed to run the single-user notebook servers.","package":"notebook","optional":true},{"reason":"Used by the default Authenticator for system-level user authentication.","package":"PAM (Pluggable Authentication Module)","optional":false}],"imports":[{"note":"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`).","symbol":"Config object (c)","correct":"# In jupyterhub_config.py, configuration is set via the 'c' object\nc.JupyterHub.port = 8000\nc.Authenticator.admin_users = {'youradminuser'}\nc.Authenticator.allowed_users = {'user1', 'user2'}"},{"note":"Used when implementing a custom authenticator plugin for JupyterHub.","symbol":"Authenticator","correct":"from jupyterhub.auth import Authenticator"},{"note":"Used when implementing a custom spawner plugin for JupyterHub.","symbol":"Spawner","correct":"from jupyterhub.spawner import Spawner"}],"quickstart":{"code":"# 1. Generate a default configuration file:\njupyterhub --generate-config\n\n# 2. Edit jupyterhub_config.py to allow users (or all authenticated users)\n# (Replace 'your_username' with your actual system username)\n# You might add something like:\n# c.Authenticator.allowed_users = {'your_username'}\n# c.Authenticator.admin_users = {'your_username'}\n# If you want to allow any user who can authenticate on the system (Unix users):\n# c.Authenticator.auto_authenticate = True\n\n# 3. Start JupyterHub (requires root privileges by default, or specific configuration for non-root)\njupyterhub","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All major version upgrades (e.g., <4.0.0 to >=4.0.0, <5.0.0 to >=5.0.0)"},{"fix":"For Windows environments, it is strongly recommended to run JupyterHub within a Docker container or a Linux virtual machine.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Upgrading JupyterHub, especially with the default `configurable-http-proxy` managed by JupyterHub, will cause service disruption for users.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `DummyAuthenticator`'s password option has been deprecated.","severity":"deprecated","affected_versions":"Versions >= 5.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"User 'my-username' not allowed (403 Forbidden)"},{"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.","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).","error":"500: Internal Server Error after spawning my single-user server"},{"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`.","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.","error":"JupyterHub proxy fails to start"},{"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.","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.","error":"Permission denied: $PREFIX/etc/jupyter/lab (or similar permission errors in shared environments)"}]}