# Getting started

> Install DuckLocal on macOS, Windows or Linux, add the ducklocal CLI, open a CSV, Parquet, JSON or Excel file and run your first DuckDB SQL query.

Source: https://ducklocal.app/docs/getting-started

**[中文](zh/getting-started.md)**

DuckLocal is a desktop app for asking questions of the data files on your
machine with SQL. There is no server to run, no connection to configure, and
no account — you point it at files and start querying. This page takes you
from download to your first result in about five minutes.

## 1. Install {#install}

DuckLocal runs on macOS, Windows, and Linux. The links below download the latest release from `dl.ducklocal.app`; the same files and release notes are available on [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest).

These guides are updated for [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0), released November 4, 2026. It adds [agent workflows](agent-workflows.md): restricted SQL, a checked handoff to the window, dashboard proposals, analysis records and portable projects. Dashboards also place line and scatter charts by time, and gzipped JSON and CSV open as data. If you're updating from before 0.3.0, reinstall your extensions: that release moved DuckLocal to DuckDB 2.0.

### Mac

You need **macOS 12 or later on Apple silicon** (M1 or newer).

1. Download [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg).
2. Open it and drag **DuckLocal** onto **Applications**.
3. Launch DuckLocal from Applications or Spotlight.

The disk image is signed and notarized by Apple, so it opens without any
Gatekeeper workaround.

### Windows

You need **64-bit Windows 10 or later**.

1. Download [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) and extract it.
2. Run `ducklocal.exe` from the extracted folder. The build is not
   code-signed yet, so the first launch may show **Windows protected your
   PC** — choose **More info**, then **Run anyway**.

### Linux

You need an **x86_64** system with **glibc 2.35 or newer** (Ubuntu 22.04,
Debian 12, Fedora 36 or later) and graphics drivers with Vulkan support.

```bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
```

::: details Building from source instead
You need Rust stable 1.85.1 or newer and a C++ toolchain (Xcode Command Line
Tools). DuckDB is compiled from vendored sources, so the first build takes
several minutes and a few gigabytes of disk.

```bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal
```

The binary is `./target/release/ducklocal`; use it wherever this guide says
`ducklocal`. See [Development](development.md) for bundling a `.app`.
:::

## 2. Add the `ducklocal` command (optional) {#add-command}

Everything in the app works without a terminal. If you also want to open data
from the command line — or let an AI agent analyze it with the
[CLI](cli.md) — add the command from the app:

1. Click the robot button in the title bar, or choose
   **DuckLocal → Command line & AI…** from the menu bar.
2. Click **Install command**. On a Mac, the system asks for your password
   to write to `/usr/local/bin`.
3. Open a new terminal and check it: `ducklocal --version`.

The command is a link to the app, so updating DuckLocal updates the command
too. To update, click the version at the right end of the status bar: a newer
release downloads and installs when you restart (see [Update check](settings-and-data.md#update-check)). It goes in `/usr/local/bin` on a Mac and `~/.local/bin` on Linux; on
Windows the app's folder is added to your `Path`.

In the same dialog, **Add to Claude Code** installs the DuckLocal skill so
Claude Code knows how to query your files, and **Copy brief** copies a short
explanation to paste into any other AI agent. See
[AI CLI and official skill](cli.md#install-the-official-skill).

::: details Adding it by hand
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal
```

To remove it: `sudo rm /usr/local/bin/ducklocal`. On Linux, link the extracted
binary into `~/.local/bin`; on Windows, add the extracted folder to your `Path`.
:::

## 3. Open some data

The first launch starts with a short guide, led by the duck: bringing in your
AI agent, opening data, the sidebar, running a query and reading its results.
**Skip** closes it at any step. To see it again, choose **Show the guide** from
the **DuckLocal** menu on a Mac, or from the right-click menu of the version at
the right end of the status bar.

Behind it is a screen titled **Drop your data in**. From here, any of these
gets data in:

- **Drag** CSV, TSV, Parquet, JSON or Excel files — or a whole folder — onto
  the window.
- Click **Open files** or **Open folder**.
- On a Mac, **double-click** a `.parquet` or `.duckdb` file in Finder, or
  choose DuckLocal under **Open With** for CSV, JSON and Excel files. See
  [Open from Finder](data-sources.md#open-from-finder).
- From a terminal, name the paths:

  ```bash
  ducklocal ./sales.csv         # one file
  ducklocal ./logs/             # every data file under a folder, recursively
  ducklocal './data/*.parquet'  # a pattern — quote it so the shell does not expand it first
  ducklocal warehouse.duckdb    # an existing DuckDB database
  ```

Each file becomes a view named after the file — `sales.csv` becomes `sales` —
and shows up under **Local files** in the sidebar with its columns and row
count. DuckLocal reads the files where they are; nothing is copied or
uploaded.

Files you open are remembered, so the next launch starts with the same
workspace. [Data sources](data-sources.md) has the details on formats,
folders, patterns and databases.

On a Mac you can also peek at a file before opening it: select it in Finder
and press **Space**. DuckLocal's [Quick Look preview](data-sources.md#quick-look)
shows the columns and first rows of Parquet, DuckDB, CSV, TSV and JSON Lines
files.

::: tip No data handy?
The [first-10-minutes tutorial](tutorial.md) walks through a small sample
file step by step.
:::

## 4. Run a query

Click **New query** (or open some data — the editor appears on its own). Type
SQL and press **⌘↵** (Cmd+Enter; Ctrl+Enter on Windows and Linux):

```sql
SELECT * FROM sales LIMIT 20;
```

Replace `sales` with any view name from your sidebar.

The result appears in the panel under the editor. Switch it to **Chart** for a
quick picture, or export it as CSV or Parquet. The toolbar above the editor
has **Run**, **Format** and **EXPLAIN**.

A shortcut worth knowing: in the sidebar, click the play button beside a
table to get a ready-made `SELECT * … LIMIT 100`, or a column name to select
just that column.

## Where to go next

- [Your first 10 minutes](tutorial.md) — a guided tour with sample data
- [Data sources](data-sources.md) — formats, folders, patterns, databases, Finder and Quick Look
- [SQL editor](sql-editor.md) — tabs, shortcuts, autocompletion, EXPLAIN
- [Results and charts](results-and-charts.md) — filtering, export, charts, the column overview
- [Dashboards (.dash)](dashboards.md) — dashboards as text files, and reviewing them with an AI agent
- [Troubleshooting](troubleshooting.md) — when something does not behave