Configuring backend¶

Configuration Files¶

Like the Jupyter Notebook server, JupyterHub, and other Jupyter interactive computing tools, jupyter-lsp can be configured via Python or JSON files in well-known locations. You can find out where to put them on your system with:

jupyter --paths

They will be merged from bottom to top, and the directory where you launch your notebook server wins, making it easy to check in to version control.

Configuration Options¶

language_servers¶

jupyter-lsp does not come with any Language Servers! However, we will try to use known language servers if they are installed and we know about them: you can disable this behavior by configuring autodetect.

If you don't see an implementation for the language server you need, continue reading!

Please consider contributing your language server spec to jupyter-lsp!

The absolute minimum language server spec requires:

• argv, a list of shell tokens to launch the server in stdio mode (as opposed to tcp),
• the languages which the server will respond to, and
• the schema version of the spec (currently 2)

# ./jupyter_notebook_config.json                 ---------- unique! -----------
#                                               |                              |
# or e.g.                                       V                              V
# $PREFIX/etc/jupyter/jupyter_notebook_config.d/a-language-server-implementation.json
{
  "LanguageServerManager": {
    "language_servers": {
      "a-language-server-implementation": {
        "version": 2,
        "argv": ["/absolute/path/to/a-language-server", "--stdio"],
        "languages": ["a-language"]
      }
    }
  }
}

A number of other options we hope to use to enrich the user experience are available in the schema.

More complex configurations that can't be hard-coded may benefit from the python approach:

# jupyter_notebook_config.py
import shutil

# c is a magic, lazy variable
c.LanguageServerManager.language_servers = {
    "a-language-server-implementation": {
        # if installed as a binary
        "argv": [shutil.which("a-language-server")],
        "languages": ["a-language"],
        "version": 2
    },
    "another-language-implementation": {
        # if run like a script
        "argv": [shutil.which("another-language-interpreter"), "another-language-server"],
        "languages": ["another-language"],
        "version": 2
    }
}

nodejs¶

default: None

An absolute path to your nodejs executable. If None, nodejs will be detected in a number of well-known places.

autodetect¶

default: True

If True, jupyter-lsp will look for all known language servers. User-configured language_servers of the same implementation will be preferred over autodetected ones.

node_roots¶

default: []

Absolute paths to search for directories named node_modules, such as nodejs-backed language servers. The order is, roughly:

• the folder where notebook or lab was launched
• the JupyterLab staging folder
• wherever conda puts global node modules
• wherever some other conventions put it

extra_node_roots¶

default: []

Additional places jupyter-lsp will look for node_modules. These will be checked before node_roots, and should not contain the trailing node_modules.

virtual_documents_dir¶

default: os.getenv("JP_LSP_VIRTUAL_DIR", ".virtual_documents")

Path to virtual documents relative to the content manager root directory.

Its default value can be set with JP_LSP_VIRTUAL_DIR environment variable and fallback to .virtual_documents.

Python entry_points¶

pip-installable packages in the same environment as the Jupyter notebook server can be automatically detected as providing language_servers. These are a little more involved, but also more powerful: see more in Contributing. Servers configured this way are loaded before those defined in configuration files, so that a user can fine-tune their available servers.