JupyterLab Server Components

2.28.0 · active · verified Sun Mar 29

jupyterlab-server provides a set of REST API handlers and utilities that serve as the backend components for JupyterLab and similar applications. It acts as an intermediary layer between JupyterLab and Jupyter Server, allowing for the creation of custom JupyterLab-like environments. The library maintains an active development pace with frequent updates, often on a monthly or bi-monthly release cycle.

Warnings

breaking In 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.
Fix: Update `c.ServerApp.template_dir` to `c.ServerApp.templates_dir` in your Jupyter configuration files (e.g., `jupyter_jupyterlab_server_config.py`).
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.
Fix: When 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.
gotcha When 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.
Fix: Consult the `jupyter_server` migration guides for updating import paths and extension loading mechanisms. Use `jupyterlab_server` specific imports where available.
deprecated JupyterLab 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.
Fix: Ensure `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.

Install

pip install jupyterlab-server Default Install
pip install jupyterlab-server[openapi] With OpenAPI support

Imports

LabHandler
```
from jupyterlab_server.handlers import LabHandler
```
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.

Quickstart

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()

view raw JSON →