DuckLocal Docs

English

简体中文

English

简体中文

Appearance

Getting started ​

中文

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 ​

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.

These guides are updated for v0.4.0, released November 4, 2026. It adds agent workflows: 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.
  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 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
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 for bundling a .app.

2. Add the ducklocal command (optional) ​

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

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.

  • 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 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 shows the columns and first rows of Parquet, DuckDB, CSV, TSV and JSON Lines files.

No data handy?

The first-10-minutes tutorial 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 ​

Released under the Apache-2.0 License.