jupyter-lsp acts as a multi-language server WebSocket proxy for Jupyter Notebook and JupyterLab servers. It enables advanced IDE-like features such as code navigation, hover suggestions, linters, and autocompletion in Jupyter environments by leveraging the Language Server Protocol (LSP). It works in conjunction with a frontend extension, typically `jupyterlab-lsp`, and specific language servers (e.g., `python-lsp-server`). The library is actively maintained, with version 2.3.0 being the current stable release, supporting Python >=3.8.
Install & Compatibility
Where this runs
tested against v2.3.1 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jupyter_lsp
✓ jupyter-lsp is primarily a server extension and not typically imported directly in user-facing Python code within a notebook or script for its core functionality.
Its functionality is enabled by installing it as a Jupyter server extension. Configuration is done via Jupyter config files (JSON or Python) rather than direct Python imports for end-users.
This quickstart guides you through installing `jupyter-lsp`, its JupyterLab frontend counterpart `jupyterlab-lsp`, and a common Python language server. After installation, a restart of JupyterLab is crucial for the extensions to be recognized. Language server configurations can then be managed through JupyterLab's settings.
# Install jupyter-lsp and the JupyterLab frontend extension
pip install jupyter-lsp jupyterlab-lsp 'jupyterlab>=4.1.0'
# Install a language server for Python (e.g., python-lsp-server)
pip install python-lsp-server
# If using other languages, install their respective LSP servers, e.g., for R:
# Rscript -e 'install.packages("languageserver")'
# After installation, restart your JupyterLab instance to enable the extensions.
# You can then verify the installation and configure language servers via:
# JupyterLab Settings -> Settings Editor -> Language Servers (Experimental)
# Example of how you might enable the server extension if not auto-detected (less common now):
# jupyter server extension enable jupyter_lsp --py --sys-prefix
# To verify server extensions are enabled (run in terminal):
# jupyter server extension list
Debug
Known issues
gotchaInstalling `jupyter-lsp` alone is not enough; you must also install a separate frontend extension (like `jupyterlab-lsp` for JupyterLab) AND at least one language server (e.g., `python-lsp-server` for Python) to get any LSP features. `jupyter-lsp` is only the backend proxy.fixEnsure `jupyterlab-lsp` is installed for JupyterLab, and install the specific language server(s) for the languages you intend to use.
affects: All versions
gotchaJupyterLab (and sometimes Jupyter Notebook) must be restarted after installing `jupyter-lsp` and `jupyterlab-lsp` for the extensions and language servers to be properly recognized and activated.fixClose and reopen your JupyterLab or Jupyter Notebook session after installation.
affects: All versions
gotchaFor Python, disabling Jedi (e.g., `%config Completer.use_jedi = False` in IPython or in `ipython_config.py`) can prevent conflicts and improve autocompletion performance when using LSP servers like `python-lsp-server` (which often use Jedi internally).fixTemporarily run `%config Completer.use_jedi = False` in a notebook cell, or add `c.Completer.use_jedi = False` to your `ipython_config.py` for a permanent solution.
affects: All versions
breaking`jupyter-lsp` versions 0.x were designed for Jupyter Notebook Server, while versions 1.x and above are for Jupyter Server. Installing `jupyter-lsp` 2.x with an older Jupyter Notebook environment might lead to unexpected behavior or failure to load.fixEnsure your Jupyter environment is compatible. For `jupyter-lsp` 2.x, use Jupyter Server or a recent JupyterLab installation (which typically bundles Jupyter Server).
affects: Pre-1.0 to 1.x and 2.x
breakingConfiguration keys for language servers have changed over time. For example, `language_servers` became `languageServers` and `pyls.serverSettings` became `pylsp.configuration`. Using old configuration keys can prevent language servers from loading or behaving as expected.fixConsult the `jupyter-lsp` documentation for the correct configuration key names for your installed version. Update your `jupyter_server_config.json` or Python configuration files accordingly.
affects: Older versions transitioning to newer ones (exact transition points vary per key)
gotchaBy default, Jupyter Server might restrict access to files outside its root directory. For LSP features like 'Jump to Definition' to work with system-wide installed packages or virtual environments, you might need to create a symlink to your system root (e.g., `.lsp_symlink` in your Jupyter root) or configure `jupyter_server_config.py` to allow broader file access.fixCreate a symlink (`.lsp_symlink`) in your Jupyter root pointing to `/` (or `C:\` on Windows), or modify `jupyter_server_config.py` as per documentation to extend file access.
affects: All versions on Linux/OSX, potentially others depending on server configuration
breakingAttempting to run shell commands like `pip install` directly within a Python script (e.g., `/script.py`) will result in a `SyntaxError`. Shell commands must be executed using appropriate methods such as `subprocess.run()` or by running the script from a shell.fixExecute `pip install jupyter-lsp jupyterlab-lsp 'jupyterlab>=4.1.0'` directly in your shell/terminal, or if running from a Python script, use `import subprocess; subprocess.run(['pip', 'install', 'jupyter-lsp', 'jupyterlab-lsp', 'jupyterlab>=4.1.0'])`.
affects: All Python versions
breaking`pip install` is a shell command and cannot be directly executed as Python syntax within a `.py` file. Attempting to do so will result in a `SyntaxError`.fixEnsure `pip install` commands are executed in a shell environment (e.g., via a `.sh` script or directly in the terminal). If running from a Python script, use `subprocess.run(['pip', 'install', 'package_name'])` or similar methods to invoke shell commands.
affects: All Python versions (this is a fundamental language syntax rule)
Audit
Dependencies
jupyterlab-lsprequiredProvides the frontend (JupyterLab) integration for LSP features.
jupyterlabrequiredThe primary Jupyter frontend environment where jupyter-lsp is typically used. Requires >=4.1.0 for recent jupyterlab-lsp versions.
python-lsp-serveroptionalAn example of a specific language server needed for Python LSP features. Users must install appropriate language servers for their desired languages (e.g., 'bash-language-server', 'vscode-html-languageserver-bin').