2025년 3월, DuckDB 1.2.1이 DuckDB UI와 함께 나왔습니다. duckdb -ui를 실행하면 내 컴퓨터에서 돌고 있는 DuckDB 프로세스를 기반으로 브라우저에 노트북이 열립니다. 그 뒤로 DuckLocal에 대해 가장 자주 받는 질문은 대개 “DuckDB UI를 그냥 쓰면 되지 않나요?” 같은 형태입니다.

타당한 질문입니다. 두 도구 모두 DuckDB를 로컬에서 실행하고, 직접 관리할 서버가 필요 없으며, 쿼리와 데이터를 내 컴퓨터에 둡니다. 하지만 출발점이 다르고, 그 차이가 어떤 작업에 어느 쪽이 맞는지를 결정합니다. 이 글은 그 차이를 솔직하게 정리해 보려는 시도입니다. 제가 직접 DuckDB UI를 선택하는 경우까지 포함해서요.

1. 한 줄 결론

이런 경우…선택
이미 DuckDB CLI나 Python에서 작업 중이고 그 세션을 시각적으로 보고 싶다DuckDB UI
SQL 셀 노트북 방식이 익숙하다DuckDB UI
MotherDuck을 쓰거나 MotherDuck을 통해 결과를 공유하고 싶다DuckDB UI
CSV, Parquet, JSON, Excel 파일과 폴더가 잔뜩 쌓인 곳에서 시작한다DuckLocal
오프라인으로 작업해야 하거나, 도구의 모든 부분이 설치되어 검토 가능하길 원한다DuckLocal
차트와 대시보드를 파일로 저장해 git에 두고 싶다DuckLocal
AI 에이전트가 터미널에서 같은 데이터를 쿼리하길 원한다DuckLocal
같은 데이터에서 둘 다 쓰고 싶다DuckLocal, 그다음 CALL start_ui();

2. DuckDB UI란 무엇인가

DuckDB UI는 MotherDuck이 만들고 유지 관리하며, ui라는 DuckDB 확장 기능으로 제공됩니다. 터미널에서 duckdb -ui로 시작하거나, CLI, Python, Java 등 어떤 DuckDB 클라이언트에서든 CALL start_ui();로 시작합니다.

이 확장 기능은 자신을 호출한 DuckDB 프로세스 안에서 localhost(기본 포트 4213)에 HTTP 서버를 띄우고 브라우저를 엽니다. UI는 바로 그 프로세스와 통신하므로, 프로세스가 보는 것을 모두 봅니다. 연결된 데이터베이스, 메모리, 그리고 로컬 파일까지요.

브라우저에서 얻는 것:

  • 노트북 — 이름을 붙여 저장하는 SQL 셀 모음으로, 구문 강조와 자동 완성이 있습니다. 셀 하나에 여러 문장을 담을 수 있습니다.
  • 연결된 데이터베이스 브라우저와 테이블 요약: 행 수, 열, 타입, 열별 프로파일.
  • Column Explorer — 결과를 요약하고 각 열을 파고들어 볼 수 있습니다.
  • 선택적 MotherDuck 로그인 — 테이블을 MotherDuck의 클라우드 웨어하우스에 저장하고 공유할 수 있습니다. 옵트인 방식이며, 기본적으로 아무것도 내 컴퓨터를 떠나지 않습니다.

비교를 위해 중요한 점이 두 가지 있습니다. 첫째, 확장 기능의 로컬 서버가 UI 자체의 프런트엔드 파일을 https://ui.duckdb.org에서 가져옵니다. 인터페이스를 최신으로 유지하기 위해서인데, 쿼리는 여전히 로컬에서 실행되지만 UI 자체는 네트워크에서 불러옵니다. 출시 당시 오프라인 사용은 지원되지 않았습니다. 둘째, 확장 기능은 MIT 라이선스인 반면, 출시 당시 프런트엔드 소스는 공개되지 않았습니다.

출처: DuckDB UI 발표 · UI 확장 기능 문서 · GitHub의 duckdb/duckdb-ui. 이 글을 쓴 뒤 바뀐 내용은 이 링크들에서 확인하세요.

3. 항목별 비교

항목DuckDB UIDuckLocal
무엇인가DuckDB의 ui 확장 기능이 제공하는 브라우저 노트북DuckDB를 내장한 네이티브 데스크톱 앱
시작 방법어떤 DuckDB 클라이언트에서든 duckdb -ui 또는 CALL start_ui();(1.2.1 이상)앱을 열거나 ducklocal ./data/ 실행
쿼리 실행 위치시작한 DuckDB 프로세스 안, 내 컴퓨터에서DuckLocal에 내장된 DuckDB, 내 컴퓨터에서
인터페이스 파일로컬 서버가 ui.duckdb.org에서 가져옴앱과 함께 배포됨
오프라인UI 파일을 위해 네트워크가 필요함오프라인에서 동작하며, 네트워크는 S3, 지도 타일, 확장 기능 설치, 직접 켠 업데이트 확인에만 사용됨
데이터 가져오기SQL: read_csv, ATTACH, 또는 세션에 이미 있는 데이터파일, 폴더, glob 패턴을 끌어다 놓으면 뷰가 되고 다음 실행에도 남음
작업 방식SQL 셀 노트북쿼리 탭, 스키마 사이드바, 기록, EXPLAIN, 프로파일러
결과 탐색테이블 요약과 Column Explorer결과 그리드, 열별 개요 탭, 내장 차트
재사용과 공유저장한 노트북, 선택적 MotherDuck 공유검토하고 git에 둘 수 있는 일반 텍스트 .dash 대시보드와 플롯 주석
AI 에이전트주된 목표가 아님경계가 정해진 JSON을 내는 ducklocal CLI와 공식 에이전트 스킬
소스확장 기능은 MIT, 프런트엔드는 출시 당시 미공개Apache-2.0, 앱과 소스는 GitHub에 공개
플랫폼windows_arm64를 제외하고 DuckDB가 동작하는 곳Apple silicon의 macOS, Windows x64, Linux x86_64

가장 짧게 말하면 이렇습니다. DuckDB UI는 이미 가지고 있는 DuckDB 세션을 들여다보는 창입니다. DuckLocal은 보고 싶은 파일을 중심으로 만들어진 그 세션 자체입니다.

4. DuckDB UI를 써야 할 때

이미 DuckDB가 작업 공간일 때

작업이 DuckDB CLI나 Python 스크립트 안에서 이뤄진다면 UI는 명령 하나로 열리고, 새 앱이 필요 없습니다. duckdb -ui my.duckdb를 실행하거나, 이미 데이터를 불러와 변환한 Python 프로세스에서 start_ui()를 호출하면 바로 그 상태를 봅니다. DuckLocal은 다른 프로세스 내부를 볼 수 없지만, UI는 그러라고 만들어진 도구입니다.

노트북 방식으로 사고할 때

어떤 분석은 순서를 지키고 싶은 긴 단계의 연속입니다. 불러오기, 정리, 조인, 확인, 요약. 이름을 붙여 저장하는 셀 노트북은 그런 작업에 잘 맞고, 셀 하나에서 여러 문장을 한 번에 실행할 수 있습니다. DuckLocal의 쿼리 탭은 긴 이야기를 이어 가는 것보다 여러 질문을 따로따로 던지는 데 더 적합합니다.

MotherDuck을 쓸 때

팀이 이미 MotherDuck으로 데이터를 공유한다면 UI는 자연스러운 프런트엔드입니다. 로그인하면 같은 노트북이 로컬 DuckDB와 클라우드 웨어하우스 양쪽에 닿습니다. DuckLocal에는 클라우드 서비스가 없고, 만들 계획도 없습니다.

내 컴퓨터용 DuckLocal 빌드가 없을 때

DuckLocal은 Apple silicon의 macOS, Windows x64, Linux x86_64용으로 배포됩니다. 예를 들어 Intel Mac에서는 DuckLocal을 소스에서 직접 빌드해야 하지만, DuckDB UI는 DuckDB가 도는 곳이면 어디서든(ARM Windows 제외) 실행됩니다.

5. DuckLocal을 써야 할 때

SQL이 아니라 파일에서 시작할 때

CSV, Parquet 파일이 담긴 폴더, 또는 ./logs/2026-*/*.json 같은 패턴을 끌어다 놓으면 각각이 쿼리할 수 있는 뷰가 되고 그 열이 사이드바에 나타납니다. Excel 통합 문서의 비어 있지 않은 시트는 모두 테이블이 됩니다. 먼저 read_csv(…)라고 쓸 필요가 없고, 다음에 앱을 열어도 파일은 그대로 남아 있습니다.

오프라인으로 동작해야 하거나, 전부 검토 가능해야 할 때

DuckLocal의 인터페이스는 설치한 앱의 일부입니다. 실행 중에 인터페이스 코드를 불러오지 않고, 확장 기능을 스스로 내려받지 않으며, 업데이트 확인도 직접 켜기 전까지 꺼져 있습니다. 반면 DuckDB UI의 프런트엔드는 UI를 시작할 때 가져오고, DuckDB에 로드된 데이터를 읽을 수 있습니다. DuckDB 문서 자체도 신뢰하는 URL에만 연결하라고 권고합니다. 대부분의 사람에게는 문제가 되지 않습니다. 하지만 보안 검토, 감사, 규제 대상 데이터, 에어갭 환경에서는 “모든 것이 설치되어 있고 오픈 소스”라는 점이 더 강한 보장입니다.

차트와 대시보드를 파일로 갖고 싶을 때

결과는 그 자리에서 막대, 선, 산점도, 원형, 지도 차트로 바뀝니다. 남겨 둘 가치가 있는 뷰라면 .dash 파일이 쿼리, 플롯, 필터를 일반 텍스트로 기술합니다. diff를 뜨고, 풀 리퀘스트에서 검토하고, ducklocal check로 검증할 수 있습니다.

AI 에이전트와 함께 작업할 때

ducklocal CLI는 스키마를 먼저 보는 단일 문장 SQL 워크플로를 경계가 정해진 JSON 출력과 함께 에이전트에 제공하고, 대시보드 주석을 통해 특정 차트에 대한 질문을 에이전트에 넘길 수 있습니다. 같은 파일이 앱에도 열려 있어 에이전트의 작업을 직접 확인할 수 있습니다.

6. DuckLocal 안에서 DuckDB UI 실행하기

둘 중 하나를 고를 필요는 없습니다. DuckDB UI는 확장 기능이고 DuckLocal은 DuckDB 확장 기능을 로드할 수 있습니다. 그래서 UI는 DuckLocal 자체의 DuckDB 인스턴스 위에서 동작합니다:

  1. DuckLocal 사이드바에서 확장 기능 탭을 엽니다.
  2. ui 행에서 설치를 클릭한 다음 로드를 클릭합니다. DuckLocal은 확장 기능을 스스로 설치하지 않으므로 이 단계는 의도적으로 수행하는 작업입니다.
  3. 쿼리 탭에서 다음을 실행합니다:
CALL start_ui();

브라우저에서 http://localhost:4213의 DuckDB UI가 열립니다. DuckLocal이 실행 중인 DuckDB 인스턴스에 연결되므로, DuckLocal에서 연 파일을 노트북에서 그대로 사용할 수 있습니다.

ui 확장 기능이 ‘로드됨’으로 표시된 DuckLocal의 확장 기능 탭과 옆의 데이터 놓기 시작 화면
DuckLocal의 확장 기능 탭에서 ui 확장 기능을 로드한 모습. 여기서 CALL start_ui();를 실행하면 같은 DuckDB 인스턴스에서 DuckDB UI가 열립니다.

알아 두면 좋은 점이 몇 가지 있습니다:

  • 네트워크가 필요합니다: ui를 설치할 때 한 번, 그리고 시작할 때마다 ui.duckdb.org에서 UI 파일을 가져와야 합니다.
  • DuckLocal과 함께 끝납니다. DuckLocal을 종료하면 그 DuckDB 인스턴스와 UI 서버도 함께 닫힙니다. CALL stop_ui_server();로 더 일찍 멈출 수 있고, CALL start_ui_server();는 브라우저를 열지 않고 서버만 시작합니다.
  • 노트북은 확장 기능에 속합니다. 저장 위치는 ~/.duckdb/extension_data/ui/입니다. DuckLocal의 쿼리 기록에는 UI에서 실행한 내용이 포함되지 않습니다.
  • 읽기 전용 데이터베이스에서는 직접 실행할 수 없습니다. 그런 데이터베이스는 노트북에서 ATTACH '…' (READ_ONLY)로 연결하세요.

제가 둘을 함께 쓰는 방식은 이렇습니다. DuckLocal로 데이터를 열고 열을 살펴보며 뻔한 질문을 차트로 만들고, 하나의 질문이 노트북으로 남겨 두고 싶은 긴 조사로 번지면 DuckDB UI를 씁니다.

문서: DuckLocal에서 DuckDB UI 열기 · 확장 기능 탭

7. 자주 묻는 질문

DuckDB UI와 DuckLocal의 차이는 무엇인가요?

DuckDB UI는 DuckDB의 ui 확장 기능이, 자신을 시작한 DuckDB 프로세스에서 제공하는 브라우저 노트북입니다. DuckLocal은 DuckDB를 내장한 네이티브 데스크톱 앱으로, 파일과 폴더 열기, 차트, 일반 텍스트 대시보드, AI 에이전트용 CLI를 중심으로 만들어졌습니다. 둘 다 쿼리를 로컬에서 실행합니다.

DuckLocal은 DuckDB UI를 대체하나요?

아니요. 로컬 데이터에 SQL을 실행한다는 점에서는 겹치지만, UI는 기존 DuckDB 세션을 들여다보는 창으로, DuckLocal은 파일을 위한 워크스페이스로 가장 잘 맞습니다. UI가 DuckLocal 안에서 동작하므로 둘 다 사용할 수 있습니다.

DuckDB UI는 오프라인에서 동작하나요?

쿼리는 로컬에서 실행되지만, UI의 프런트엔드 파일은 시작할 때마다 ui.duckdb.org에서 가져오므로 네트워크 접근이 필요합니다. DuckLocal의 인터페이스는 앱에 포함되어 오프라인에서도 동작합니다.

제 쿼리가 MotherDuck으로 전송되나요?

UI에서 MotherDuck에 로그인하지 않는 한 그렇지 않습니다. 기본적으로 DuckDB UI는 DuckLocal과 마찬가지로 내 컴퓨터에서 쿼리를 실행합니다.

관련 링크

← 모든 글