marimo

marimo is a reactive notebook for Python and SQL that models notebooks as dataflow graphs. When you run a cell or interact with a UI element, marimo automatically runs affected cells (or marks them as stale), keeping code and outputs consistent and preventing bugs before they happen. Every marimo notebook is stored as pure Python, executable as a script, and deployable as an app.

Getting Started

Installation

First, install marimo with SQL support:

pip

pip install "marimo[sql]"

uv

uv pip install "marimo[sql]"

conda

conda install -c conda-forge marimo duckdb polars

Authentication

There are two ways to authenticate:

1. Interactive Authentication: When you first connect to MotherDuck (e.g. ATTACH 'md:my_db'), marimo will open a browser window for authentication.
2. Token-based Authentication: Set your MotherDuck token as an environment variable:

export motherduck_token="your_token"

You can find your token in the MotherDuck UI under Account Settings.

Using MotherDuck

First, open your first notebook:

marimo edit my_notebook.py

1. Connecting and Database Discovery

SQL

ATTACH IF NOT EXISTS 'md:my_db'

Python

import duckdb

# Connect to MotherDuck
duckdb.sql("ATTACH IF NOT EXISTS 'md:my_db'")

You will be prompted to authenticate with MotherDuck when you run the above cell. This will open a browser window where you can log in and authorize your marimo notebook to access your MotherDuck database. In order to avoid being prompted each time you open a notebook, you can set the motherduck_token environment variable:

export motherduck_token="your_token"
marimo edit my_notebook.py

Once connected, your MotherDuck tables are automatically discovered in the Datasources Panel:

Browse your MotherDuck databases

2. Writing SQL Queries

You can query your MotherDuck db using SQL cells in marimo. Here's an example of how to query a table and display the results using marimo:

Query a MotherDuck table

marimo's reactive execution model extends into SQL queries, so changes to your SQL will automatically trigger downstream computations for dependent cells (or optionally mark cells as stale for expensive computations).

3. Mixing SQL and Python

marimo allows you to seamlessly combine SQL queries with Python code:

Mixing SQL and Python

Example Notebook

For a full example of using MotherDuck with marimo, check out this example notebook.