콘텐츠로 이동

시작하기 ​

DuckLocal은 컴퓨터에 있는 데이터 파일에 SQL로 질문하는 데스크톱 앱입니다. 실행할 서버도, 설정할 연결도, 계정도 없습니다. 파일을 지정하면 바로 쿼리를 시작할 수 있습니다. 이 페이지는 다운로드부터 첫 결과까지 약 5분 안에 안내합니다.

1. 설치 ​

DuckLocal은 macOS, Windows, Linux에서 실행됩니다. 아래 링크에서 dl.ducklocal.app의 최신 릴리스를 내려받을 수 있으며, 같은 파일과 릴리스 노트는 GitHub에서도 확인할 수 있습니다.

이 가이드는 2026년 11월 15일에 릴리스된 v0.4.1에 맞춰 업데이트되었습니다. 0.4.0 버전에서는 에이전트 워크플로가 추가되었습니다: 제한된 SQL, 창으로의 확인된 핸드오프, 대시보드 제안, 분석 기록, 휴대 가능한 프로젝트입니다. 0.4.1 버전에서는 다중 선택 필터, 대시보드의 시간대와 타임라인 차트, 여러 쿼리가 공유하는 SQL을 한 번만 담아 두는 view 블록, 확장 기능 탭에서 설치하는 mssql 같은 커뮤니티 확장 기능, 그리고 인메모리 데이터베이스에서 만든 테이블을 저장하도록 안내하는 프롬프트가 추가되었습니다. 0.3.0 이전 버전에서 업데이트한다면 확장 기능을 다시 설치하세요. 그 릴리스에서 DuckLocal이 DuckDB 2.0으로 옮겨졌습니다.

Mac ​

Apple silicon(M1 이상)에서 macOS 12 이상이 필요합니다.

  1. ducklocal-macos-arm64.dmg를 내려받습니다.
  2. 파일을 열고 DuckLocal을 응용 프로그램 폴더로 끌어다 놓습니다.
  3. 응용 프로그램 또는 Spotlight에서 DuckLocal을 실행합니다.

디스크 이미지는 Apple의 서명과 공증을 받았으므로 Gatekeeper를 우회하는 조치 없이 바로 열립니다.

Windows ​

64비트 Windows 10 이상이 필요합니다.

  1. ducklocal-windows-x86_64.zip을 내려받아 압축을 풉니다.
  2. 압축을 푼 폴더에서 ducklocal.exe를 실행합니다. 이 빌드는 아직 코드 서명이 되어 있지 않아 첫 실행 시 Windows에서 PC를 보호했습니다가 표시될 수 있습니다. 추가 정보를 선택한 다음 실행을 클릭하세요.

Linux ​

x86_64 시스템과 glibc 2.35 이상(Ubuntu 22.04, Debian 12, Fedora 36 이상), 그리고 Vulkan을 지원하는 그래픽 드라이버가 필요합니다.

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
대신 소스에서 빌드하기

Rust stable 1.85.1 이상과 C++ 툴체인(Xcode Command Line Tools)이 필요합니다. DuckDB는 함께 포함된 소스에서 컴파일되므로 첫 빌드에 몇 분과 수 GB의 디스크 공간이 필요합니다.

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

바이너리는 ./target/release/ducklocal입니다. 이 가이드에서 ducklocal이라고 나오는 곳에 이것을 사용하세요. .app 번들링은 개발을 참고하세요.

2. ducklocal 명령 추가하기(선택 사항) ​

앱의 모든 기능은 터미널 없이도 동작합니다. 명령줄에서 데이터를 열거나 AI 에이전트가 CLI로 데이터를 분석하게 하려면 앱에서 명령을 추가하세요:

  1. 제목 표시줄의 로봇 버튼을 클릭하거나 메뉴 막대에서 **DuckLocal → 명령줄 및 AI…**를 선택합니다.
  2. 명령 설치를 클릭합니다. Mac에서는 /usr/local/bin에 쓰기 위해 시스템이 비밀번호를 요청합니다.
  3. 새 터미널을 열고 확인합니다: ducklocal --version.

이 명령은 앱을 가리키는 링크이므로 DuckLocal을 업데이트하면 명령도 함께 업데이트됩니다. 업데이트하려면 상태 표시줄 오른쪽 끝의 버전을 클릭하세요. 새 릴리스가 내려받아지고 다시 시작할 때 설치됩니다(업데이트 확인 참고). Mac에서는 /usr/local/bin, Linux에서는 ~/.local/bin에 들어가며, Windows에서는 앱 폴더가 Path에 추가됩니다.

같은 대화 상자에서 Claude Code에 추가를 클릭하면 DuckLocal 스킬이 설치되어 Claude Code가 파일을 쿼리하는 방법을 알게 되고, 요약 복사는 짧은 설명을 복사해 다른 AI 에이전트에 붙여 넣을 수 있게 합니다. 자세한 내용은 AI CLI와 공식 스킬을 참고하세요.

직접 추가하기
bash
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. 데이터 열기 ​

첫 실행 시 오리가 안내하는 짧은 가이드가 시작됩니다. AI 에이전트 연결, 데이터 열기, 사이드바, 쿼리 실행과 결과 읽기를 차례로 소개합니다. 건너뛰기를 누르면 어느 단계에서든 닫힙니다. 다시 보려면 Mac에서는 DuckLocal 메뉴에서, 또는 상태 표시줄 오른쪽 끝 버전의 오른쪽 클릭 메뉴에서 가이드 보기를 선택하세요.

그 뒤에는 데이터를 여기에 놓으세요라는 화면이 있습니다. 여기에서는 다음 중 어떤 방법으로든 데이터를 가져올 수 있습니다:

  • CSV, TSV, Parquet, JSON, Excel 파일 또는 폴더 전체를 창으로 끌어다 놓습니다.

  • 파일 열기 또는 폴더 열기를 클릭합니다.

  • Mac에서는 Finder에서 .parquet 또는 .duckdb 파일을 더블 클릭하거나, CSV, JSON, Excel 파일의 경우 다음으로 열기에서 DuckLocal을 선택합니다. Finder에서 열기를 참고하세요.

  • 터미널에서 경로를 지정합니다:

    bash
    ducklocal ./sales.csv         # 파일 하나
    ducklocal ./logs/             # 폴더 아래의 모든 데이터 파일을 재귀적으로
    ducklocal './data/*.parquet'  # 패턴 — 셸이 먼저 확장하지 않도록 따옴표로 감싸기
    ducklocal warehouse.duckdb    # 기존 DuckDB 데이터베이스

각 파일은 파일 이름을 딴 뷰가 됩니다. sales.csv는 sales가 되고, 사이드바의 로컬 파일 아래에 열과 행 수와 함께 표시됩니다. DuckLocal은 파일을 있는 자리에서 읽으며, 아무것도 복사하거나 업로드하지 않습니다.

연 파일은 기억되므로 다음 실행 시에도 같은 워크스페이스로 시작합니다. 형식, 폴더, 패턴, 데이터베이스에 대한 자세한 내용은 데이터 소스에 있습니다.

Mac에서는 파일을 열기 전에 미리 볼 수도 있습니다. Finder에서 파일을 선택하고 스페이스를 누르세요. DuckLocal의 Quick Look 미리보기가 Parquet, DuckDB, CSV, TSV, JSON Lines 파일의 열과 처음 몇 행을 보여 줍니다.

쓸 만한 데이터가 없나요?

처음 10분 튜토리얼에서 작은 샘플 파일로 단계별로 따라 해 볼 수 있습니다.

4. 쿼리 실행하기 ​

새 쿼리를 클릭합니다(데이터를 열면 에디터가 저절로 나타납니다). SQL을 입력하고 ⌘↵(Cmd+Enter, Windows와 Linux에서는 Ctrl+Enter)를 누릅니다:

sql
SELECT * FROM sales LIMIT 20;

sales 부분은 사이드바에 있는 어떤 뷰 이름으로든 바꿔 보세요.

결과는 에디터 아래 패널에 나타납니다. 차트로 전환하면 한눈에 그림으로 볼 수 있고, CSV나 Parquet로 내보낼 수도 있습니다. 에디터 위 도구 모음에는 실행, 서식, EXPLAIN이 있습니다.

알아 두면 좋은 바로 가기가 있습니다. 사이드바에서 테이블 옆의 재생 버튼을 클릭하면 SELECT * … LIMIT 100이 바로 채워지고, 열 이름을 클릭하면 그 열만 선택됩니다.

다음에 읽을 것 ​

Apache-2.0 라이선스로 공개되었습니다.