This extension provides a native experience for working with marimo notebooks, a long-requested feature that we’ve worked hard to get right.

An LSP-first architecture

The core of our extension is a marimo notebook language server (marimo-lsp [2]). As far as we know, it’s the first notebook runtime to take this approach. The Language Server Protocol (LSP) [3] offers a small but important set of notebook-related capabilities that we use for document and kernel syncing; everything else is handled through custom actions and messages.

By building on LSP, we aim to create a path to expose marimo capabilities in additional environments (beyond VS Code/Cursor). The notebook features in LSP are still limited, but as the protocol evolves, we’ll be able to shift more functionality out of the extension and into the language server, making it available to a wider range of editors and tools. For example, this could enable:

- structural edits to notebook documents (e.g., adding or removing cells) [4]

- editor hover information that reflects the live runtime values of variables

Deep uv integration with PEP 723

Because marimo notebooks are plain Python files, we adopt PEP 723-style inline metadata [5] to describe a notebook’s environment. Tools such as uv already support this format: they read the metadata block, build or update the corresponding environment, and run the script inside it.

The marimo CLI already integrates with uv in "sandbox" mode [6] to manage an isolated environment defined by PEP 723 metadata for a single notebook. In the extension, our uv-based “sandbox controller” manages multiple notebooks: each notebook gets its own isolated, cached environment. The controller keeps the environment aligned with the dependencies declared in the file and can update that metadata automatically when imports are missing.

uv normally syncs such environments whenever you run a script, ensuring it matches the dependencies declared in its metadata; we apply this concept at the cell level so the environment stays in sync whenever cells run. The same cached uv environment is reused if you run the notebook as a script via uv (e.g., uv run notebook.py).

—-------

This work has been a complete rewrite, and we're grateful to the community for early feedback. While VS Code and the LSP support a subset of notebook features, the ecosystem has been shaped heavily by Jupyter, and we’ve had to work around some assumptions baked into existing APIs. We’ve been coordinating with the VS Code team and hope our work can help broaden the conversation—pushing the LSP notebook model forward and making room for runtimes that aren’t Jupyter-based.

We'd love to hear your thoughts!

[1] https://marimo.io

[2] https://github.com/marimo-team/marimo-lsp

[3] https://microsoft.github.io/language-server-protocol/

[4] https://github.com/microsoft/vscode-languageserver-node/issu...

[5] https://peps.python.org/pep-0723/

[6] https://docs.marimo.io/guides/package_reproducibility/