marimo + quarto = 🌴 ❤️

marimo

marimo is a next generation python notebook that is embeddable anywhere. As such, it is a great fit for quarto, which has reactive and robust a publishing system. This repo is a quarto engine extension that lets you use marimo in your quarto documents; just follow the setup below.

Important

Requires Quarto >= 1.9.20 (pre-release). This extension uses the engine extension API introduced in 1.9.20. Install with: quarto update --pre-release

Quick Start

1. Tool Installation

• Install uv
• Install Quarto (>= 1.9.20 pre-release)

2. Create a project

quarto create project

3. Add quarto-marimo to your project

quarto add marimo-team/quarto-marimo

4. Edit your index.qmd

---
title: My Document
---

# Just another Quarto project

```python {.marimo}
#| echo: true
import marimo as mo
slider = mo.ui.slider(1, 10, 1, label="Look, a slider!")
slider
```

## More things

And we can respond!

```python {.marimo}
# No echo here means we do not show the code
mo.md("NaN" * slider.value + " Batman!")
```

5. Run!

quarto preview
# uvx --with marimo --from quarto-cli quarto preview

Features

This plugin uses marimo islands 🌴 which allows marimo content to be embedded in between other content. In addition to base marimo support, some Quarto execution options are also supported:

Option	Default	Description
eval	True	Whether this code should run
echo	False	Whether to show the code in the output
output	True	Whether to show the output
warning	True	Whether to show warnings
error	True	Whether to show errors
include	True	Whether to consider the block as part of the document
editor	False	Whether to show the editor (only for marimo)

💡 Note: You can open .md and .qmd files directly in marimo like a normal notebook. Read more about it in the tutorial

📓 Check out the marimo mkdocs extension

Environment

By default, marimo will use uv to create a new virtual environment. You can specify dependencies by following our docs and setting the yaml pyproject value in your notebook.

To disable sandboxed behavior, set external-env: true in your notebook yaml; this requires an active virtual environment with marimo installed.

Note

You can add pyproject or enternal-env to your _quarto.yml file for global behavior

Note, that local files are not bound to be accessible in WASM runtimes- and on web load, dependencies are installed via micropip. As such, this is mainly advised for PDF rendering, or other output formats that do not support Javascript.

---

Development

To build the TypeScript engine extension:

quarto call build-ts-extension

This bundles src/marimo-engine.ts into _extensions/marimo/marimo-engine.js.

Migrating from v0.4.x (Lua filter)

If you were using filters: marimo-team/marimo in your YAML frontmatter, you can remove that line. The extension now auto-detects {python .marimo} code blocks. The old filters: syntax still works but will print a deprecation warning.

---

Credits: holoviz-quarto for ideas on layout