Jupyter Server provides the backend services, APIs, and REST endpoints for Jupyter web applications like Jupyter Notebook, JupyterLab, and Voila. It is a replacement for the Tornado Web Server in older Jupyter Notebook installations. Currently at version 2.17.0, it maintains an active release cadence with frequent minor updates and bug fixes.
Install & Compatibility
Where this runs
tested against v2.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 7.559s · 67.2MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 8.2s · import 6.972s · 65MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ServerApp
✓ from jupyter_server.serverapp import ServerApp
ExtensionApp
✓ from jupyter_server.extension.application import ExtensionApp
Used for developing Jupyter Server extensions.
The most common way to start Jupyter Server is via the command line with `jupyter server`. For programmatic control, the `ServerApp` can be initialized and started within a Python script. This example demonstrates a minimal programmatic startup, explicitly disabling browser opening and authentication for demonstration purposes. **For production use, it is critical to enable and properly configure authentication (tokens/passwords).**
import asyncio
import os
from jupyter_server.serverapp import ServerApp
async def start_jupyter_server():
# Instantiate the server application
# For a quickstart, we disable browser opening and token/password for simplicity.
# In production, ALWAYS secure your Jupyter Server with tokens/passwords.
app = ServerApp(
open_browser=False,
port=os.environ.get("JUPYTER_SERVER_PORT", 8888),
port_retries=0,
token="", # IMPORTANT: Do NOT use empty token in production.
password="" # IMPORTANT: Do NOT use empty password in production.
)
await app.initialize()
await app.start()
print(f"Jupyter Server running at: {app.url} (Access via web browser if not using --no-browser, use the printed URL including token if applicable)")
print("Press Ctrl+C to stop the server.")
try:
# Keep the server running until interrupted
await asyncio.Event().wait()
except KeyboardInterrupt:
print("\nServer stopping...")
finally:
await app.stop()
if __name__ == "__main__":
# To run this, save as a Python file (e.g., `run_server.py`) and execute `python run_server.py`.
# Alternatively, for a basic command-line start, simply run `jupyter server` in your terminal.
asyncio.run(start_jupyter_server())
jupyter-server --version
Debug
Known issues
breakingMigrating from Jupyter Notebook (pre-7) to Jupyter Server (v2+) involves significant breaking changes. Configuration files moved from `jupyter_notebook_config.py` to `jupyter_server_config.py`, and server-related imports from the `notebook` package should be updated to `jupyter_server`.fixMigrate `jupyter_notebook_config.py|json` to `jupyter_server_config.py|json`, changing `c.NotebookApp` references to `c.ServerApp`. Update import paths from `from notebook.x import Y` to `from jupyter_server.x import Y`. Specifically, `ServerApp.preferred_dir` is deprecated; use `FileContentsManager.preferred_dir` instead. Also note that `ServerApp.token` is deprecated, use `IdentityProvider.token` instead, and `ServerApp.password` is deprecated, use `PasswordIdentityProvider.hashed_password` instead.
affects: 2.x and later (from 1.x or older `notebook` versions)
gotchaJupyter Server defaults to token-based authentication for security. If you try to access the server without a token or a configured password, you will be prompted for authentication. Direct password login is not enabled by default when token authentication is active.fixWhen starting, note the token printed in the console and use it in the URL (`?token=your_token`). For persistent password authentication, use `jupyter server password` to set a hashed password or configure it in `jupyter_server_config.py`.
affects: All versions
gotchaMismatches between the Python environment where Jupyter Server is running and the environment where kernels are sourced can lead to `ImportError` or `ModuleNotFound` exceptions within notebooks.fixEnsure that the desired Python packages and kernel environments are correctly installed and accessible by the Jupyter Server. Use `jupyter kernelspec list` to verify available kernels and their paths. Often, installing packages into the same environment where `jupyter_server` is installed resolves this.
affects: All versions
gotchaJupyter Server (and its kernels) can crash due to excessive memory usage, often caused by very large datasets, long-running computations, or extensive cell outputs.fixMonitor memory usage. For large datasets, consider processing in chunks. For persistent issues, you may need to adjust Jupyter's configuration, such as `c.ServerApp.max_buffer_size` in `jupyter_server_config.py`, or allocate more system resources.
affects: All versions
gotchaFor remote access or specific deployments, firewall configuration is essential. The server's main port (`ServerApp.port`) must be open, as well as a range of ephemeral ports (typically 49152 to 65535) used by ZeroMQ for kernel communication.fixConfigure your firewall to allow TCP connections on the specified server port and the ephemeral port range (49152-65535). Consult your operating system or cloud provider's firewall documentation.
affects: All versions
Errors
Common errors & fixes
jupyter-server: command not found
The `jupyter-server` package is either not installed in your active Python environment or its executable script is not located in your system's PATH.
fixInstall `jupyter-server` using `pip install jupyter-server` or `conda install jupyter-server`, and ensure your environment's `Scripts` or `bin` directory is correctly added to your system's PATH.
[W ServerApp] Port 8888 is already in use
Another process or another instance of Jupyter Server is currently listening on the default port (8888) or the specific port you attempted to use.
fixEither terminate the process currently using the port, or launch Jupyter Server on an alternative port using `jupyter lab --port 8889` or `jupyter notebook --port 8889`.
Invalid JSON received for authentication
This error typically indicates a problem with the authentication handshake between the client (browser) and the Jupyter Server, often due to expired tokens, incorrect security settings, or issues with reverse proxy configurations.
fixTry clearing your browser's cache and cookies, using an incognito window, or ensuring any reverse proxy configurations are correctly passing authentication headers; if the issue persists, consider regenerating server configuration files or restarting the server.
SSL: CERTIFICATE_VERIFY_FAILED
This error occurs when the Jupyter Server is configured to use SSL/TLS, but the client (usually the web browser or another tool) cannot verify the authenticity of the server's SSL certificate, often because it's self-signed or from an untrusted authority.
fixFor self-signed certificates, configure your browser to trust the certificate, or provide the path to the certificate authority (CA) bundle in your client configuration; temporarily disabling SSL verification might also be an option for development (though not recommended for production).
Audit
Dependencies
pythonrequiredRequired to run the Jupyter Server.