Notebook Shim

0.2.4 verified Tue May 12 auth: no python install: stale quickstart: stale

Notebook-shim is a Python library that provides a compatibility layer for applications transitioning from `jupyter/notebook` to `jupyter/jupyter_server` as their backend. It specifically helps handle traits and configuration that moved between these two core Jupyter components. The current version is 0.2.4, and it is released on an as-needed basis to support the evolution of the Jupyter ecosystem.

pip install notebook-shim

Common errors

error A _jupyter_server_extension_points function was not found in notebook_shim. Instead, a _jupyter_server_extension_paths function was found and will be used for now. This function name will be deprecated in future releases of Jupyter Server. ↓

cause The `notebook-shim` library is using an older extension entry point (`_jupyter_server_extension_paths`) that has been superseded by `_jupyter_server_extension_points` in newer versions of Jupyter Server.

fix

This is a deprecation warning, not an error preventing functionality. The notebook-shim project will need to update its implementation to use the newer _jupyter_server_extension_points function in future releases. Users should ensure both notebook-shim and jupyter-server are updated to their latest compatible versions.

error ModuleNotFoundError: No module named 'notebook_shim' ↓

cause The `notebook-shim` package is not installed in the currently active Python environment, or Jupyter is running with a different Python environment than where `notebook-shim` was installed.

fix

Install notebook-shim using pip or conda in the Python environment that Jupyter is configured to use:

pip install notebook-shim
# or if using conda
conda install notebook-shim

After installation, restart the Jupyter kernel or server.

error Error using notebook_shim with jupyter_nbextensions_configurator ↓

cause There is a known compatibility issue between `notebook-shim` and the `jupyter_nbextensions_configurator` extension, likely due to conflicting ways they interact with Jupyter's configuration or extension loading mechanisms during the transition from `jupyter/notebook` to `jupyter/jupyter_server`.

fix

Check the official GitHub repositories and issue trackers for both notebook-shim and jupyter_nbextensions_configurator for specific workarounds, compatibility notes, or updated versions that resolve this conflict. Sometimes, upgrading both packages or temporarily disabling one of the extensions can help diagnose or resolve the issue.

Warnings

breaking Direct inheritance from `notebook.notebookapp.NotebookApp` for server-side extensions is deprecated. You must migrate to `jupyter_server.serverapp.ServerApp` and use `notebook_shim.NotebookConfigShimMixin` for compatibility. ↓

fix Ensure `notebook-shim` is installed (e.g., `pip install notebook-shim`). Then, import `NotebookConfigShimMixin` from its specific submodule, typically `from notebook_shim.notebook.mixins import NotebookConfigShimMixin`, and include it in your application's inheritance list: `class MyExtension(NotebookConfigShimMixin, ServerApp):`.

gotcha The `notebook-shim` library is a compatibility layer, not a full replacement for `jupyter/notebook`. It's designed to ease the transition, but applications should aim for full `jupyter_server` compatibility over time. ↓

fix Refer to the `jupyter_server` documentation for best practices on developing extensions and applications natively against `jupyter_server`.

deprecated There is an open issue regarding the deprecation of `_jupyter_server_extension_paths` in `jupyter_server`, which might affect how extensions are discovered or loaded in the future. ↓

fix Monitor the `jupyter/notebook_shim` and `jupyter/jupyter_server` GitHub repositories for updates on extension path discovery mechanisms and adapt your extension registration accordingly.

breaking The `NotebookConfigShimMixin` class could not be imported from the `notebook_shim` package. This typically indicates that `notebook_shim` is either not installed, or an incompatible version is installed. `NotebookConfigShimMixin` was introduced in `notebook-shim` version 0.2.0. ↓

fix Ensure `notebook_shim` is installed and updated to at least version 0.2.0 or higher. For example: `pip install 'notebook-shim>=0.2.0'`.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 67.4M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 8.3s - 65M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 75.1M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 8.7s - 72M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 65.5M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 7.6s - 63M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 65.3M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 7.3s - 63M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 67.6M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 10.1s - 65M

3.9 slim (glibc) - - - -

Imports

NotebookConfigShimMixin
wrong
```
from notebook.notebookapp import NotebookApp
```
correct
```
from notebook_shim import NotebookConfigShimMixin
```
Applications subclassing `NotebookApp` to leverage the Python server backend should now switch to `ExtensionApp` from `jupyter_server` and add `NotebookConfigShimMixin` to handle moved traits.

Quickstart stale last tested: 2026-04-24

This quickstart demonstrates the primary use case of `notebook-shim`: integrating `NotebookConfigShimMixin` into an application that now extends `jupyter_server.serverapp.ServerApp` instead of the legacy `notebook.notebookapp.NotebookApp`.

from jupyter_server.serverapp import ServerApp
from notebook_shim import NotebookConfigShimMixin

class MyShimmedApp(NotebookConfigShimMixin, ServerApp):
    # Your application's custom logic here
    pass

if __name__ == '__main__':
    # In a real application, you would run this via `jupyter-server` entrypoints.
    # For a direct example, you can instantiate and start it minimally.
    print("This example demonstrates the import path and class inheritance.")
    print("To run a functional server, integrate MyShimmedApp with jupyter_server's extension system.")