# 시작하기

> macOS, Windows, Linux에 DuckLocal을 설치하고 ducklocal CLI를 추가한 뒤 CSV, Parquet, JSON, Excel 파일을 열어 첫 DuckDB SQL 쿼리를 실행하는 방법을 설명합니다.

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

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

## 1. 설치 {#install}

DuckLocal은 macOS, Windows, Linux에서 실행됩니다. 아래 링크에서 `dl.ducklocal.app`의 최신 릴리스를 내려받을 수 있으며, 같은 파일과 릴리스 노트는 [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest)에서도 확인할 수 있습니다.

이 가이드는 2026년 11월 15일에 릴리스된 [v0.4.1](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.1)에 맞춰 업데이트되었습니다. 0.4.0 버전에서는 [에이전트 워크플로](agent-workflows.md)가 추가되었습니다: 제한된 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`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg)를 내려받습니다.
2. 파일을 열고 **DuckLocal**을 **응용 프로그램** 폴더로 끌어다 놓습니다.
3. 응용 프로그램 또는 Spotlight에서 DuckLocal을 실행합니다.

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

### Windows

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

1. [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/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
```

::: details 대신 소스에서 빌드하기
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` 번들링은 [개발](development.md)을
참고하세요.
:::

## 2. `ducklocal` 명령 추가하기(선택 사항) {#add-command}

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

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

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

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

::: details 직접 추가하기
```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에서 열기](data-sources.md#open-from-finder)를 참고하세요.
- 터미널에서 경로를 지정합니다:

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

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

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

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

::: tip 쓸 만한 데이터가 없나요?
[처음 10분 튜토리얼](tutorial.md)에서 작은 샘플 파일로 단계별로 따라 해 볼 수 있습니다.
:::

## 4. 쿼리 실행하기

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

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

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

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

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

## 다음에 읽을 것

- [처음 10분](tutorial.md) — 샘플 데이터로 따라 하는 안내 투어
- [데이터 소스](data-sources.md) — 형식, 폴더, 패턴, 데이터베이스, Finder와 Quick Look
- [SQL 에디터](sql-editor.md) — 탭, 바로 가기 키, 자동 완성, EXPLAIN
- [결과와 차트](results-and-charts.md) — 필터링, 내보내기, 차트, 열 개요
- [대시보드(.dash)](dashboards.md) — 텍스트 파일로서의 대시보드와 AI 에이전트와의 검토
- [문제 해결](troubleshooting.md) — 뭔가 이상하게 동작할 때
