Начало работы
DuckLocal — настольное приложение, которое отвечает на вопросы о файлах данных на вашем компьютере с помощью SQL. Здесь не нужно запускать сервер, настраивать подключение или заводить учётную запись: вы указываете на файлы и начинаете запросы. Эта страница проведёт вас от загрузки до первого результата примерно за пять минут.
1. Установка
DuckLocal работает на macOS, Windows и Linux. Ссылки ниже скачивают последнюю версию с dl.ducklocal.app; те же файлы и примечания к выпуску есть на GitHub.
Эти руководства обновлены для v0.4.1, выпущенной 15 ноября 2026 года. Версия 0.4.0 добавила сценарии работы с агентами: ограниченный SQL, проверяемую передачу в окно, предложения дашбордов, записи анализа и переносимые проекты. Версия 0.4.1 добавляет фильтры с множественным выбором, часовой пояс и график временной шкалы для дашбордов, блоки view, которые хранят общий SQL один раз, расширения сообщества, такие как mssql, на вкладке «Расширения», а также запрос на сохранение таблиц, созданных во встроенной базе данных. Если вы обновляетесь с версии до 0.3.0, переустановите расширения: в том выпуске DuckLocal перешёл на DuckDB 2.0.
Mac
Нужна macOS 12 или новее на Apple silicon (M1 или новее).
- Скачайте
ducklocal-macos-arm64.dmg. - Откройте его и перетащите DuckLocal в Программы.
- Запустите DuckLocal из папки «Программы» или через Spotlight.
Образ диска подписан и нотаризован Apple, поэтому открывается без каких-либо обходных путей для Gatekeeper.
Windows
Нужна 64-битная Windows 10 или новее.
- Скачайте
ducklocal-windows-x86_64.zipи распакуйте его. - Запустите
ducklocal.exeиз распакованной папки. Сборка пока не подписана кодом, поэтому при первом запуске может появиться Windows защитила ваш компьютер — выберите Подробнее, затем Выполнить в любом случае.
Linux
Нужна система x86_64 с glibc 2.35 или новее (Ubuntu 22.04, Debian 12, Fedora 36 или новее) и графические драйверы с поддержкой Vulkan.
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Сборка из исходного кода
Нужен стабильный Rust 1.85.1 или новее и цепочка инструментов C++ (Xcode Command Line Tools). DuckDB компилируется из включённых исходников, поэтому первая сборка занимает несколько минут и несколько гигабайт диска.
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocalБинарный файл — ./target/release/ducklocal; используйте его везде, где в этом руководстве указано ducklocal. О сборке .app см. в разделе Разработка.
2. Добавьте команду ducklocal (необязательно)
Всё в приложении работает без терминала. Если вы также хотите открывать данные из командной строки — или позволить ИИ-агенту анализировать их через CLI — добавьте команду из приложения:
- Нажмите кнопку с роботом в строке заголовка или выберите DuckLocal → Командная строка и ИИ… в строке меню.
- Нажмите Установить команду. На Mac система запросит пароль для записи в
/usr/local/bin. - Откройте новый терминал и проверьте:
ducklocal --version.
Команда — это ссылка на приложение, поэтому обновление DuckLocal обновляет и команду. Чтобы обновиться, нажмите на версию в правом конце строки состояния: более новая версия скачается и установится при перезапуске (см. Проверку обновлений). На Mac команда размещается в /usr/local/bin, на Linux — в ~/.local/bin; в Windows папка приложения добавляется в Path.
В том же диалоге Добавить в Claude Code устанавливает навык DuckLocal, чтобы Claude Code знал, как запрашивать ваши файлы, а Скопировать краткую справку копирует короткое объяснение для вставки в любой другой ИИ-агент. См. CLI для ИИ и официальный навык.
Добавление вручную
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocalЧтобы удалить: sudo rm /usr/local/bin/ducklocal. На Linux слинкуйте распакованный бинарный файл в ~/.local/bin; в Windows добавьте распакованную папку в Path.
3. Откройте данные
При первом запуске открывается короткое руководство, которое ведёт утка: подключение ИИ-агента, открытие данных, боковая панель, выполнение запроса и чтение результатов. Пропустить закрывает его на любом шаге. Чтобы увидеть его снова, выберите Показать руководство в меню DuckLocal на Mac или в контекстном меню версии в правом конце строки состояния.
За ним — экран с заголовком Перетащите сюда свои данные. Отсюда данные добавляются любым из способов:
Перетащите файлы CSV, TSV, Parquet, JSON или Excel — или целую папку — в окно.
Нажмите Открыть файлы или Открыть папку.
На Mac дважды щёлкните файл
.parquetили.duckdbв Finder или выберите DuckLocal в разделе Открыть с помощью для файлов CSV, JSON и Excel. См. Открытие из Finder.Из терминала укажите пути:
bashducklocal ./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
Каждый файл становится представлением (view) с именем по имени файла — sales.csv превращается в sales — и появляется в Локальных файлах в боковой панели со своими столбцами и числом строк. DuckLocal читает файлы там, где они лежат; ничего не копируется и не загружается.
Открытые файлы запоминаются, поэтому следующий запуск начинается с тем же рабочим пространством. Подробности о форматах, папках, шаблонах и базах данных — в разделе Источники данных.
На Mac можно также заглянуть в файл до открытия: выберите его в Finder и нажмите Пробел. Предпросмотр Quick Look в DuckLocal показывает столбцы и первые строки файлов Parquet, DuckDB, CSV, TSV и JSON Lines.
Нет подходящих данных под рукой?
В учебнике для первых 10 минут шаг за шагом разбирается небольшой файл с примером.
4. Выполните запрос
Нажмите Новый запрос (или откройте данные — редактор появится сам). Введите SQL и нажмите ⌘↵ (Cmd+Enter; в Windows и Linux — Ctrl+Enter):
SELECT * FROM sales LIMIT 20;Замените sales на любое имя представления из боковой панели.
Результат появится на панели под редактором. Переключите её на График, чтобы быстро увидеть картину, или экспортируйте результат в CSV или Parquet. На панели инструментов над редактором есть Выполнить, Формат и EXPLAIN.
Полезный приём: в боковой панели нажмите кнопку воспроизведения рядом с таблицей, чтобы получить готовый SELECT * … LIMIT 100, или имя столбца, чтобы выбрать только этот столбец.
Что дальше
- Ваши первые 10 минут — пошаговое знакомство с данными из примера
- Источники данных — форматы, папки, шаблоны, базы данных, Finder и Quick Look
- Редактор SQL — вкладки, сочетания клавиш, автодополнение, EXPLAIN
- Результаты и графики — фильтрация, экспорт, графики, обзор столбцов
- Дашборды (.dash) — дашборды как текстовые файлы и их рецензирование с ИИ-агентом
- Решение проблем — когда что-то ведёт себя не так
