# MotherDuck for Excel add-in
> Install the MotherDuck add-in for Excel on Mac, Windows, or the web to load tables and PivotTables, refresh them, and write ranges back.
MotherDuck for Excel is an add-in that opens a MotherDuck pane inside Excel. Use it to find a table, pick columns and filters, and load the data into an Excel Table or PivotTable. Saved imports refresh with one click, and you can write a range back to MotherDuck as a new table, a replacement, appended rows, or updates by key. It works in Excel for Mac, Excel on Windows, and Excel on the web, with no driver to install.

:::info[Experimental]
The add-in is an early preview. It can change or break without notice. Write back changes real tables, so try it on data you can re-create.
:::

The pane runs DuckDB in Excel and connects to MotherDuck with your own account, so queries run on your own Duckling with your own permissions. No other service sits between Excel and MotherDuck.

## Prerequisites

- A MotherDuck account
- Microsoft 365 Excel: Excel for Mac 16.35 or later, Excel on Windows version 2002 or later, or Excel on the web
- To write back, a read/write account or [access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token). A [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) can import and refresh only.

## Install the add-in

The install page at [motherduck.com/labs/excel](https://motherduck.com/labs/excel/) has the same steps, a download for each installer, and the uninstall commands. Pick the Excel you use:

### Mac

**Option 1: one command**

1. Quit Excel (⌘Q).
2. Open **Terminal**, paste this command, and press **Return**:

   ```bash
   curl -fsSL https://motherduck.com/labs/excel/install/install-mac.sh | bash
   ```

3. Excel starts. Open a workbook, then select **Home** → **MotherDuck**.

**Option 2: installer**

1. Quit Excel (⌘Q).
2. Download the [installer](https://motherduck.com/labs/excel/install/MotherDuck-for-Excel-Install-Mac.zip), open the zip, then open **Install MotherDuck for Excel**.
3. The installer isn't signed yet, so macOS blocks it the first time. Choose **Done**, open **System Settings** → **Privacy & Security**, select **Open Anyway**, then open the installer again.
4. Excel starts. Open a workbook, then select **Home** → **MotherDuck**.

Both options run the same [script](https://motherduck.com/labs/excel/install/install-mac.sh), which copies the add-in's manifest into Excel's add-in folder and clears Excel's add-in cache. Nothing else is installed.

To remove the add-in, quit Excel and run:

```bash
curl -fsSL https://motherduck.com/labs/excel/install/install-mac.sh | bash -s -- --uninstall
```

### Windows

**Option 1: one command**

1. Save your work and close Excel.
2. Open **PowerShell** (no admin rights needed), paste this command, and press **Enter**:

   ```powershell
   irm https://motherduck.com/labs/excel/install/install-windows.ps1 | iex
   ```

3. Excel starts. Open a workbook, then select **Home** → **MotherDuck**.

**Option 2: installer**

1. Save your work and close Excel.
2. Download the [installer](https://motherduck.com/labs/excel/install/MotherDuck-for-Excel-Install.cmd) and open it.
3. The installer isn't signed yet. If your browser asks whether to keep the file, choose **Keep**. If Windows shows a security prompt, choose **Run**, or **More info** → **Run anyway**.
4. Excel starts. Open a workbook, then select **Home** → **MotherDuck**.

Both options run the same [script](https://motherduck.com/labs/excel/install/install-windows.ps1), which saves the add-in's manifest and registers it with Excel for your Windows user.

To remove the add-in, close Excel and run in PowerShell:

```powershell
irm https://motherduck.com/labs/excel/install/uninstall-windows.ps1 | iex
```

### Excel on the web

1. Download the [add-in file](https://motherduck.com/labs/excel/manifest.prod.xml) (right-click → **Save link as**, or use the download button on the [install page](https://motherduck.com/labs/excel/)).
2. In Excel on the web, open a workbook and select **Home** → **Add-ins** → **More Add-ins** → **Upload My Add-in**.
3. Choose the downloaded file and select **Upload**.
4. Select **Home** → **MotherDuck**.

An uploaded add-in lasts for the browser session, so upload it again next time. To remove it earlier, select **Home** → **Add-ins** → **My Add-ins**, then **⋯** → **Remove** next to MotherDuck.

:::tip[Deploy to your organization]
A Microsoft 365 admin can deploy the add-in to everyone or to a group, so it appears in Excel without an install. In the [Microsoft 365 admin center](https://admin.microsoft.com), go to **Settings** → **Integrated apps** → **Add-ins** → **Deploy Add-in**, and provide the manifest URL `https://motherduck.com/labs/excel/manifest.prod.xml`. The add-in only asks for permission to read and write the open workbook. See Microsoft's guide to [deploying add-ins in the admin center](https://learn.microsoft.com/microsoft-365/admin/manage/manage-deployment-of-add-ins).
:::

## Connect to MotherDuck

1. Select **Home** → **MotherDuck** to open the pane.
2. Select **Sign in with MotherDuck**. A window opens for the sign-in and closes by itself when you're done.
3. To stay signed in when you close the pane, check **Remember on this device**. Otherwise the sign-in lasts until the pane closes.

To connect with an access token instead, select **Use an access token instead**, paste a token from MotherDuck **Settings** → **Access Tokens**, and select **Connect with token**.

![Connect screen with Sign in with MotherDuck, Remember on this device, and the access token field opened under Use an access token instead](../img/excel-add-in-connect.png)

The first connection in an Excel session downloads and starts DuckDB in the pane, which takes a few seconds. Once connected, the header shows your organization and user name, and the pane has three tabs: **New import**, **Saved imports**, and **Write back**. To sign out, select your user name in the header, then **Sign out**.

## Import a table

### Find a table

On the **New import** tab, type in **Search tables and views** to search every database you can access, including databases shared with you. The search matches loosely, so `nyctaxi` finds `sample_data.nyc.taxi`. You can also expand a database to browse its schemas and tables.

Use the filter button next to the search box to show only **Tables** or **Views**, and only databases that are **Yours** or **Shared with you**. Select the refresh button to reload the list after creating a table elsewhere.

Select a table or view to open the import editor.

### Choose columns

Under **Columns**, check the columns to load. For each column you can:

- Rename it in Excel with the pencil button, without changing MotherDuck
- Move it up or down to change the column order
- Mark it as a key column with the key button, so a later [write back](#write-back-to-motherduck) can update rows by key

### Filter, sort, and limit

Filters, sorting, and row limits run in MotherDuck, so only the rows you ask for come into Excel.

1. Under **Filters**, select **Add filter**, then choose a column and an operator, such as **equals**, **contains**, **at least**, **is one of**, or **is empty**.
2. Type a value, or select the value picker button next to the value to pick from the column's values. The picker lists up to 5,000 of the most common values with their counts.
3. To make the filter follow a cell, select a cell in the sheet, then select the link button. Every refresh reads the cell's current value. With **is one of**, link a range to filter on all of its values.
4. Under **Sort and limit**, select **Add sort** to order the rows, and set a **Row limit** to load at most that many rows.

![Import editor for sample_data.nyc.taxi with six columns selected and the value picker open on a passenger_count filter](../img/excel-add-in-import-editor.png)

### Preview and load

1. Under **Preview**, select **Preview** to see the first 100 rows and the total row count. Select **Show SQL** to see the query the add-in runs.
2. Under **Destination**, choose **New sheet**, or **At a cell** to place the table at a cell you pick. You can also set the sheet and Excel table names.
3. Check **Also create a PivotTable (new sheet)** to get a PivotTable over the loaded table.
4. Select **Save and load**. The data loads into an Excel Table, and the import is saved in the workbook so you can [refresh it](#refresh-saved-imports).

Use the arrow next to **Save and load** to choose **Load without saving** for a one-off load, or **Save only** to save the import without loading it yet.

Imports stop at 250,000 rows by default. To change the limit, open **⋮** → **Settings** in the pane header and set **Row cap**, up to Excel's limit of 1,048,575 rows per sheet.

## Import as a pivot table

To summarize a table that's too big for a sheet, let MotherDuck aggregate it and load only the summary:

1. In the import editor, set **Import as** to **Pivot**.
2. Under **Rows** and **Columns**, select **Add field** to choose the fields to group by.
3. Under **Values**, choose an aggregation (**Sum**, **Average**, **Min**, **Max**, **Count**, or **Distinct count**) and a column. Choose **(rows)** to count rows.
4. Add filters if you need them, then select **Save and load**.

![Pivot import editor with passenger_count as rows, payment_type as columns, and sum of total_amount and average of tip_amount as values](../img/excel-add-in-pivot-editor.png)

The summary goes into an Excel Table, and a native PivotTable is laid out on a new sheet next to it. Refreshing runs the aggregation again and keeps your changes to the PivotTable.

:::note
Excel computes subtotals and grand totals from the grouped rows. For **Average**, a subtotal is the average of the group averages, and for **Distinct count** it's the sum of the group counts.
:::

## Import with SQL

### Write a SQL query

1. On the **New import** tab, select **SQL**.
2. Write a query, for example:

   ```sql
   SELECT passenger_count, count(*) AS trips, avg(total_amount) AS avg_total
   FROM sample_data.nyc.taxi
   WHERE trip_distance >= :min_distance
   GROUP BY ALL
   ORDER BY passenger_count;
   ```

3. Select **Get columns**. For each `:name` parameter, type a value under **Parameters**, or select a cell and then the link button to read the value from that cell at every refresh.
4. Preview and load the result as described in [Preview and load](#preview-and-load).

Parameter values are sent as values, never pasted into the SQL. Use `CAST(:name AS DATE)` when a parameter needs a type. Queries must be a single `SELECT`: statements that change data or settings are refused. To create or change tables, use [Write back](#write-back-to-motherduck).

### Generate the SQL with AI

1. Select the sparkle button in the pane header.
2. Choose a **Database**. Optionally, under **Limit to tables**, choose the tables the question is about.
3. Type a question, for example "Which payment type has the highest average tip?", and select **Generate SQL**.
4. Check the generated SQL, edit it if needed, and select **Preview and import**. The query opens in the import editor, ready to preview and load.

![Ask AI with the question about the highest average tip and the SQL that MotherDuck generated for sample_data](../img/excel-add-in-ask-ai.png)

Ask AI uses the [`prompt_sql`](/sql-reference/motherduck-sql-reference/ai-functions/sql-assistant/prompt-sql/) function, which counts toward your AI usage.

## Refresh saved imports

The **Saved imports** tab lists every import saved in the workbook. Saved imports are stored in the workbook itself, without any credentials, so they travel with the file.

![Saved imports tab with a taxi_summary pivot import, its row count, and the Refresh all button](../img/excel-add-in-saved-imports.png)

- Select the refresh button on an import to reload it, or **Refresh all** to reload every import.
- A refresh keeps the Excel table where it is, even if you moved or renamed it, and keeps PivotTables connected to it. Filters and parameters linked to cells use the cells' current values.
- The **⋯** menu on an import has **Go to data**, **Edit**, **Duplicate**, **Export JSON**, and **Delete**. Deleting an import keeps its table and data in the sheet.
- **Export all** and **Import** copy saved imports as JSON, to back them up or move them to another workbook.

## Write back to MotherDuck

Use the **Write back** tab to send a range or Excel Table to MotherDuck. Every write shows a preview first, and nothing changes until you confirm.

1. Choose a mode:
   - **Create new table**: fails if the table exists
   - **Overwrite existing table**: replaces its rows and columns
   - **Append rows**: adds the rows, matching columns by name
   - **Update or insert by key**: updates rows whose key exists and inserts the rest
2. Under **Destination**, choose the **Database**, and type a **Table name** or pick an existing **Table**. For **Update or insert by key**, choose the **Key columns** that identify a row. The table's primary key is selected by default.
3. Under **Data in Excel**, select the data in the sheet and select **Use selection**. Select a single cell in an Excel Table to use the whole table, including rows added later.
4. Select **Preview changes**. The preview shows what will happen, for example "Append 120 rows to orders" or "2 new, 3 updated, 9 unchanged in sales_targets", and any problems with a link to the Excel cells.
5. Under **Columns**, rename, retype, or skip columns, or map them to existing columns. For **Update or insert by key**, the preview lists before and after values for the updated rows.
6. Leave **Save this write-back to push again later** checked to reuse it, then select **Create table**, **Replace table**, or **Write to MotherDuck**.

![Write-back preview for update or insert by key, showing 2 new, 3 updated, and 9 unchanged rows with before and after values](../img/excel-add-in-write-back-preview.png)

Column types are detected from the cells: whole numbers become `BIGINT`, decimals `DOUBLE`, date-formatted cells `DATE` or `TIMESTAMP`, `TRUE` and `FALSE` become `BOOLEAN`, and anything else `VARCHAR`. Empty cells and Excel errors become `NULL`. When you overwrite or append to a table, its column types are kept where the values fit.

Saved write-backs appear at the top of the tab. Select the upload button on one to preview and push the current data again.

:::warning
Write back changes real tables. Try it on a scratch database first, and use a read scaling token when you only need to read.
:::

## Use MotherDuck formulas

The add-in adds two formulas that spill their results into the sheet and recalculate like any formula. They use the pane's sign-in, so connect in the pane first.

| Formula | Returns |
| --- | --- |
| `=MOTHERDUCK.TABLE(name, [columns], [limit])` | Rows of a table or view, with a header row. `name` is `"database.schema.table"` or `"database.table"`. `columns` is an optional range or array of column names. `limit` defaults to 1,000 rows. |
| `=MOTHERDUCK.SQL(query, [parameters])` | The result of a `SELECT` query, with a header row. `parameters` is an optional two-column range of `:name` names and values. |

For example:

```text
=MOTHERDUCK.TABLE("sample_data.nyc.taxi", {"passenger_count","total_amount"}, 100)
=MOTHERDUCK.SQL("SELECT count(*) AS trips FROM sample_data.nyc.taxi WHERE passenger_count = :n", A1:B1)
```

In the second example, `A1` holds `n` and `B1` holds the value. Dates in parameter cells arrive as numbers, so pass them as text with `TEXT(B1, "yyyy-mm-dd")`.

## Open workbooks from other people

A workbook can contain saved imports, write-backs, and formulas that run with your MotherDuck access. So MotherDuck only runs in workbooks allowed on your device. A workbook you start yourself is allowed automatically.

When you open a workbook from someone else that contains MotherDuck content, the pane shows **Review before MotherDuck runs here**. Select **Review** to see every import with its SQL, every write-back, and every formula. Select **Allow** only if you trust where the workbook came from. Until then, refreshes, write-backs, and formulas don't run, and formulas show `#N/A`.

## Known limitations

- **Excel on the web is slower.** It writes about 4,000 rows per second, about 10 times slower than desktop Excel. For large tables, add filters, use a PivotTable import, or use desktop Excel. If Excel on the web shows errors on wide tables, lower **Rows per write** in **Settings**.
- **Row limits:** imports stop at the row cap, 250,000 rows by default, and Excel holds at most 1,048,575 rows per sheet.
- **Write back size:** up to 5 million cells per write, and about 900 KB of text in a single row.
- **Network access:** the pane must reach `app.motherduck.com`, `api.motherduck.com` and its regional hosts, `ext.motherduck.com`, and `extensions.duckdb.org`. Locked-down networks have to allow them.
- **Settings are per device:** the row cap and other settings in **⋮** → **Settings** are stored on each device, not in the workbook.

## Troubleshooting

### The pane says it can't load the add-in

Excel can't reach the add-in. Check your internet connection, then select **Retry**. If it persists, reinstall the add-in from the [install page](https://motherduck.com/labs/excel/).

### Connecting never finishes

The pane couldn't download or start DuckDB. Check that your network allows the hosts listed in [Known limitations](#known-limitations).

### "MotherDuck no longer accepts this token"

The token expired or was revoked. Sign in again, or paste a new token.

### A formula shows `#N/A` "MotherDuck is paused in this workbook"

The workbook isn't allowed on your device yet. Open the pane, review the banner at the top, and select **Allow**. See [Open workbooks from other people](#open-workbooks-from-other-people).

### The pane shows an old version

Right-click the pane and select **Reload**, or reopen the workbook.

## Related

- [Connect MotherDuck to Excel with ODBC](/integrations/bi-tools/excel/odbc/): Power Query and the DuckDB ODBC driver on Windows
- [Authenticate to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/)
- [`prompt_sql`](/sql-reference/motherduck-sql-reference/ai-functions/sql-assistant/prompt-sql/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fbi-tools%2Fexcel%2Fadd-in%2F&page_title=MotherDuck%20for%20Excel%20add-in&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
