Skip to content

Language Server Protocol (LSP)

The marimo editor supports the Language Server Protocol (LSP) to provide enhanced code intelligence features like:

  • Code completion
  • Hover information
  • Go to definition
  • Error checking and diagnostics

Multiple language servers can be run simultaneously. When enabled, their results are merged — for example, you can get completions from pylsp and diagnostics from basedpyright at the same time.

For language server installation with --sandbox, see Sandbox mode.

Supported language servers

pylsp (python-lsp-server)

The core Python language server providing completions, hover, go-to-definition, diagnostics, code actions, rename, and signature help.

Install:

pip install "marimo[lsp]"
# or
uv add "marimo[lsp]"
# or
conda install -c conda-forge python-lsp-server python-lsp-ruff

This installs:

You may optionally install other pylsp plugins (e.g. pylsp-mypy).

Configuration:

pyproject.toml
[tool.marimo.language_servers.pylsp]
enabled = true               # Enable/disable pylsp
enable_mypy = true           # Type checking with mypy (enabled by default, if installed)
enable_ruff = true           # Linting with ruff (enabled by default, if installed)
enable_flake8 = false        # Linting with flake8
enable_pydocstyle = false    # Check docstring style
enable_pylint = false        # Linting with pylint
enable_pyflakes = false      # Syntax checking with pyflakes

basedpyright

A type checker for Python built on Pyright. In marimo, basedpyright is used for diagnostics only (type checking errors and warnings).

Install:

uv pip install basedpyright

Configuration:

pyproject.toml
[tool.marimo.language_servers.basedpyright]
enabled = true

See the basedpyright docs for more information.

ty

A type checker for Python from Astral (the creators of Ruff). In marimo, ty is used for diagnostics only.

Install:

uv pip install ty

Configuration:

pyproject.toml
[tool.marimo.language_servers.ty]
enabled = true

See the ty docs for more information.

pyrefly

A type checker for Python from Meta. Pyrefly provides completions, hover, go-to-definition, and diagnostics.

Install:

uv pip install pyrefly

Configuration:

pyproject.toml
[tool.marimo.language_servers.pyrefly]
enabled = true

See the pyrefly docs for more information.

GitHub Copilot

AI-powered code completions via the GitHub Copilot language server. Copilot is configured separately from the other language servers through the completion settings.

Configuration:

pyproject.toml
[tool.marimo.completion]
copilot = "github"

See the AI completion guide for more details on Copilot setup and configuration.

Using multiple language servers

You can enable multiple language servers at once. marimo uses a federated architecture that merges results from all active servers. For example, you might use pylsp for completions and code actions while relying on basedpyright or ty for stricter type-checking diagnostics.

Diagnostics

Diagnostics from all language servers can be toggled globally:

pyproject.toml
[tool.marimo.diagnostics]
enabled = true               # Show diagnostics in the editor

WebAssembly

Language servers are not available when running marimo in WebAssembly.

Sandbox mode (--sandbox)

With --sandbox, the editor and notebook code run in separate environments. Language servers run in the editor environment, which includes packages from the Python environment that launches marimo.

  • pylsp is installed automatically through marimo's lsp extra.
  • basedpyright, ty, and pyrefly must be installed in the environment that launches marimo. Installing them only in the notebook's sandbox does not make them available to the editor.

When you launch marimo, use --with to include a language server:

uv run --with basedpyright marimo edit --sandbox notebook.py
uv run --with ty marimo edit --sandbox notebook.py
uv run --with pyrefly marimo edit --sandbox notebook.py

You can also install ty with uv tool install ty. The ty executable must be on PATH. basedpyright and pyrefly require importable Python packages and do not support this fallback.

Troubleshooting

If you encounter issues with a language server:

  1. Make sure you've installed the required dependencies with uv pip install "marimo[lsp]"
  2. For basedpyright, ty, and pyrefly, ensure Node.js is installed
  3. If you use --sandbox, follow the sandbox installation instructions.
  4. Check if the language server is enabled in your configuration
  5. Try restarting the marimo server
  6. Check the terminal for error messages or the log files in your marimo log directory (e.g. ~/.cache/marimo/logs/)