Install & Compatibility
Where this runs
tested against v2.28.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.910 runs
installs and imports cleanly · install 0.0s · import 9.237s · 111.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 10.3s · import 8.563s · 108MB
111MB installed
● package 111MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LabHandler
✓ from jupyterlab_server.handlers import LabHandler
✗ from jupyterlab_server.server import JupyterHandler
While `JupyterHandler` might be available via `jupyter_server`, `LabHandler` is specific to `jupyterlab-server` and provides JupyterLab-specific functionality.
ServerApp
✓ from jupyterlab_server.server import ServerApp
The main application class for programmatic interaction or configuration.
add_handlers
✓ from jupyterlab_server.handlers import add_handlers
Utility to register custom request handlers to the JupyterLab server.
This quickstart illustrates how to define and conceptually register a custom API handler using `jupyterlab-server` components. Typically, `jupyterlab-server` is extended within a larger Jupyter application (like JupyterLab) via a server extension. The `load_jupyter_server_extension` function is the entry point for such extensions, where custom Tornado `web.RequestHandler`s (here, `LabHandler`) are added to the server's web application.
import os
from tornado import web
from jupyterlab_server.server import ServerApp
from jupyterlab_server.handlers import LabHandler
# Define a simple custom handler
class MyCustomHandler(LabHandler):
@web.authenticated
def get(self, path=''):
self.finish(f"Hello from My Custom Handler! Path: {path}")
# This function would typically be in a server extension module
# (e.g., `my_extension.py`) and discovered by Jupyter Server.
def load_jupyter_server_extension(server_app: ServerApp):
host_pattern = ".*$"
base_url = server_app.base_url
route_pattern = web.url(f"/{os.environ.get('MY_CUSTOM_ROUTE_PREFIX', 'my-api')}(.*)", MyCustomHandler)
server_app.web_app.add_handlers(host_pattern, [route_pattern])
server_app.log.info(f"MyCustomHandler enabled at {base_url}my-api")
# To run this for testing, you'd integrate it with a Jupyter Server setup.
# This block is illustrative and not a direct executable for end-users
# as jupyterlab-server is a component library.
# For a real setup, this would be loaded as a server extension.
# Example command to launch JupyterLab with this extension:
# jupyter lab --ServerApp.extra_static_paths='["$(pwd)"]' \
# --ServerApp.jpserver_extensions='{"my_extension": true}'
# For testing purposes (not how it's usually run in production):
# if __name__ == "__main__":
# from jupyter_server.serverapp import ServerApp as _JupyterServerApp
# class CustomLabServerApp(_JupyterServerApp):
# def initialize_settings(self):
# super().initialize_settings()
# load_jupyter_server_extension(self)
# CustomLabServerApp.launch_instance()
Debug
Known issues
breakingIn version 2.28.0, a typo was fixed in the default traitlet for the template directory, changing `template_dir` to `templates_dir`. Configurations explicitly overriding `template_dir` in earlier versions will need to be updated to `templates_dir` to maintain functionality.fixUpdate `c.ServerApp.template_dir` to `c.ServerApp.templates_dir` in your Jupyter configuration files (e.g., `jupyter_jupyterlab_server_config.py`).
affects: >=2.28.0
gotcha`jupyterlab-server` is primarily a component library providing backend services for JupyterLab and JupyterLab-like applications. It is not designed as a standalone end-user application. Direct programmatic use often involves extending its `ServerApp` or adding custom handlers within a larger Jupyter ecosystem context.fixWhen using `jupyterlab-server`, understand its role as a building block. For end-user scenarios, typically install `jupyterlab` itself. For extensions, follow the Jupyter Server extension development guidelines.
affects: All versions
gotchaWhen migrating server extensions from `notebook` (Classic Notebook) to `jupyter_server` (which `jupyterlab-server` builds upon), import paths for server modules may have changed. Code directly importing server components from the `notebook` package will need adjustment.fixConsult the `jupyter_server` migration guides for updating import paths and extension loading mechanisms. Use `jupyterlab_server` specific imports where available.
affects: Primarily for users migrating from older Jupyter Notebook server extensions to Jupyter Server / JupyterLab Server.
deprecatedJupyterLab v3.6 and later requires `jupyter_server v2.0` for Real-Time Collaboration features. While `jupyterlab-server` itself might support older `jupyter_server` versions for basic functionality, major new features in the ecosystem often mandate newer server versions.fixEnsure `jupyter_server` is updated to at least version 2.0 when aiming to use Real-Time Collaboration with JupyterLab. Check `jupyterlab-server`'s `jupyter_server` dependency range for compatibility.
affects: For JupyterLab users using RTC with versions >=3.6
Upgrade
Version history
2.28.0latest on PyPI · released Oct 22, 2025
Audit
Dependencies
jupyter_serverrequiredProvides the core server application and base handler classes that jupyterlab-server builds upon.