---
sidebar_position: 7
title: Marimo
description: Use marimo reactive notebooks with MotherDuck for interactive Python data analysis.
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# marimo

[marimo](https://marimo.io/) 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:

<Tabs groupId="install">
  <TabItem value="pip" label="pip" default>
    ```bash
    pip install "marimo[sql]"
    ```
  </TabItem>
  <TabItem value="uv" label="uv">
    ```bash
    uv pip install "marimo[sql]"
    ```
  </TabItem>
  <TabItem value="conda" label="conda">
    ```bash
    conda install -c conda-forge marimo duckdb polars
    ```
  </TabItem>
</Tabs>

### 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:

```bash
export motherduck_token="your_token"
```

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

## Using MotherDuck

First, open your first notebook:

```bash
marimo edit my_notebook.py
```

### 1. Connecting and Database Discovery

<Tabs groupId="connect">
  <TabItem value="sql" label="SQL" default>
    ```sql
    ATTACH IF NOT EXISTS 'md:my_db'
    ```
  </TabItem>
  <TabItem value="python" label="Python">
    ```python
    import duckdb

    # Connect to MotherDuck
    duckdb.sql("ATTACH IF NOT EXISTS 'md:my_db'")
    ```
  </TabItem>
</Tabs>

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:

```bash
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](../img/marimo_motherduck_db_discovery.png)

_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](../img/marimo_motherduck_sql.png)

_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).

![img](../img/marimo_motherduck_reactivity-ezgif.com-speed.gif)

### 3. Mixing SQL and Python

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

![Mixing SQL and Python](../img/marimo_motherduck_python_and_sql.png)

_Mixing SQL and Python_

## Example Notebook

For a full example of using MotherDuck with marimo, check out this [example notebook](https://github.com/marimo-team/marimo/blob/main/examples/sql/connect_to_motherduck.py).