설치 (Installation)

설치 (Installation)

원문: DuckDB Installation – DuckDB

DuckDB는 처음 실행하는 방법이 아주 간단해요. 무엇보다 좋은 점은 설치 파일 하나만 받으면 바로 쓰는 단일 파일 데이터베이스라서, 서버를 띄우거나 별도 프로세스를 관리할 필요가 없다는 거예요. 이 문서에서는 운영체제별로 DuckDB를 설치하는 방법을 차근차근 살펴볼게요.

DuckDB가 제공하는 설치 방식

DuckDB는 크게 세 가지 방식으로 설치할 수 있어요. 어느 쪽을 선택하느냐는 어디서, 어떤 언어로 쓰려는지에 따라 달라져요.

  • CLI (Command Line Interface) — 터미널에서 바로 쓰는 명령줄 도구예요. 가장 간단하게 시작하는 방법이죠.
  • 클라이언트 라이브러리 — Python, R, Java, Node.js, Go, Rust, C/C++ 같은 언어 안에서 DuckDB를 임베드해서 쓰는 방식이에요. 각 언어의 설치 도구(pip, npm, cargo 등)로 받아요.
  • ODBC / Wasm — ODBC는 Excel 같은 도구에서 접속할 때, Wasm은 브라우저에서 쓸 때 필요해요.

이 문서에서는 주로 CLI 설치에 집중하고, 언어별 클라이언트는 간단히 짚어볼게요. CLI 설치 방식만 익혀도 대부분의 작업은 시작할 수 있어요.

버전 선택: current와 LTS

설치를 준비하기 전에 버전 얘기를 하나 해둘게요. DuckDB는 페이지에서 두 가지 버전을 제공해요.

  • 1.5.5 (current) — 현재 안정 버전이에요. 새로운 기능을 가장 먼저 쓰고 싶다면 이쪽을 골라요.
  • 1.4.5 (LTS) — 장기 지원 버전이에요. 운영 환경처럼 안정성이 최우선이라면 이쪽이 더 편안해요.

다음 버전(프리뷰/야간 빌드)을 미리 보고 싶다면 preview (nightly) 페이지를 방문하면 돼요. 아래 명령어들은 대부분 current 버전 기준이에요.

Linux에 설치하기

가장 흔한 예로 Linux부터 시작해볼게요. DuckDB는 리눅스에서 설치 스크립트 한 줄로 도커 이미지 없이도 바로 설치할 수 있어요.

설치 스크립트

터미널에서 아래 명령어를 실행하면 curl이 설치 스크립트를 받아서 bash로 실행해요. 관리자 권한이 없어도 사용자 홈 디렉터리에 설치되니 편해요.

curl https://install.duckdb.org | bash

만약 LTS 버전(1.4.5)을 명시적으로 받고 싶다면 환경 변수로 버전을 지정할 수 있어요.

curl https://install.duckdb.org | DUCKDB_VERSION=1.4.5 bash

Docker 이미지

Docker를 쓰는 환경이라면 이미지를 내려받아 실행하는 방법도 있어요. 아래 명령어는 현재 폴더($(pwd))를 컨테이너 안 /workspace에 마운트하고 그 폴더에서 작업해요. 덕분에 컨테이너를 빠져나와도 파일은 내 컴퓨터에 남아 있어요. --rm은 컨테이너 종료 시 이미지를 지우라는 옵션이에요.

docker run --rm -it -v "$(pwd):/workspace" -w /workspace duckdb/duckdb

LTS 버전을 쓰려면 이미지 태그를 붙이면 돼요.

docker run --rm -it -v "$(pwd):/workspace" -w /workspace duckdb/duckdb:1.4.5

직접 다운로드 (Direct Download)

배포판 패키지로 관리하고 싶지 않다면 압축 파일을 직접 받아서 풀어도 돼요. DuckDB는 glibc 기반 빌드와 musl libc 기반 빌드를 따로 제공해요. Alpine Linux처럼 musl을 쓰는 배포판이 아니라면 glibc 빌드(권장) 를 받으면 돼요.

  • duckdb_cli-linux-amd64.zip — glibc, x86-64
  • duckdb_cli-linux-arm64.zip — glibc, ARM64
  • duckdb_cli-linux-amd64-musl.zip — musl, Alpine용
  • duckdb_cli-linux-arm64-musl.zip — musl, Alpine ARM용

압축을 풀면 실행 파일 하나가 있는데, 그게 바로 DuckDB CLI예요. 아래 링크에서 받을 수 있어요 (SHA256은 파일 무결성 확인용이에요).

macOS에 설치하기

macOS에서는 패키지 매니저가 가장 편해요. Homebrew를 쓰고 있다면 단 한 줄이면 끝나요.

brew install duckdb

스크립트나 Docker 방식은 Linux와 동일하게 쓸 수 있어요. macOS는 Intel과 Apple Silicon을 함께 지원하는 유니버설 빌드 하나로 제공되니, 아키텍처를 신경 쓸 필요가 없어서 좋아요.

curl https://install.duckdb.org | bash

docker run --rm -it -v "$(pwd):/workspace" -w /workspace duckdb/duckdb

직접 받고 싶다면 아래 파일을 쓰면 돼요.

Windows에 설치하기

Windows에서는 winget 패키지 매니저가 제일 깔끔해요.

winget install DuckDB.cli

LTS 버전을 명시적으로 받으려면 버전을 붙여요.

winget install DuckDB.cli --version 1.4.5

설치 스크립트 (Beta)

실험적인 기능이긴 한데, PowerShell에서 스크립트로 설치하는 방법도 있어요. 이 스크립트는 아직 Beta 단계라서 쓸 때 주의가 필요하다는 점을 기억해 두세요. 실행 메뉴나 명령 프롬프트에서 아래처럼 불러올 수 있어요.

powershell -NoExit iex (iwr "https://install.duckdb.org/install.ps1").Content

Docker 이미지 (WSL2용)

Windows에서 Docker를 쓴다면 WSL2 환경 위에서 같은 이미지를 실행해요.

docker run --rm -it -v "$(pwd):/workspace" -w /workspace duckdb/duckdb

직접 다운로드

압축 파일을 직접 받을 수도 있어요.

Windows에서는 한 가지 주의할 점이 있어요. DuckDB가 동작하려면 Microsoft Visual C++ Redistributable (VC++ 런타임) 이 설치되어 있어야 해요. 대부분의 Windows에는 이미 들어 있지만, 없다면 최신 지원 버전을 먼저 설치해 주세요.

언어별 클라이언트 설치하기

DuckDB의 진가는 특정 언어 안에 임베드해서 쓰는 방식이에요. 사용하는 언어에 따라 설치는 아래처럼 간단해요. 각각의 상세한 사용법은 해당 클라이언트 문서에서 확인하면 돼요.

Python

Python은 pip 하나로 끝나요. 데이터 분석 환경에서는 가장 널리 쓰이는 조합이죠.

pip install duckdb

LTS 버전을 고정하고 싶다면 버전을 붙이면 돼요.

pip install duckdb==1.4.5

R

R에서는 CRAN에서 패키지를 설치해요. DBI 인터페이스도 함께 쓰는 경우가 많아요.

install.packages("duckdb")

리눅스 환경이라면 Posit Public Package Manager의 리눅스 빌드를 명시적으로 지정할 수도 있어요.

options(HTTPUserAgent = sprintf("R/%s R (%s)",
    getRversion(),
    paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])
))
install.packages("duckdb", repos="https://p3m.dev/cran/__linux__/manylinux_2_28/latest/")

메인 CRAN에 없는 신버전을 미리 써보고 싶다면 DuckDB의 r-universe 저장소에서 받을 수도 있어요.

install.packages("DBI")
install.packages("duckdb.1.4", repos = "https://duckdb.r-universe.dev"))

Java (JDBC)

Java는 JDBC 드라이버를 JAR로 받거나, 빌드 도구가 알아서 받게 하면 돼요.

직접 다운로드:

Maven을 쓴다면 dependency를 추가하면 돼요.

<dependency>
    <groupId>org.duckdb</groupId>
    <artifactId>duckdb_jdbc</artifactId>
    <version>1.5.5.1</version>
</dependency>

Gradle이라면 아래처럼 선언해요.

implementation("org.duckdb:duckdb_jdbc:1.5.5.1")

Node.js

Node.js에는 두 가지 패키지가 있어요. @duckdb/node-api 는 네이티브 DuckDB 바인딩이고, @duckdb/duckdb-wasm 은 브라우저와 Node에서 동작하는 WebAssembly 버전이에요.

npm install @duckdb/node-api
npm install @duckdb/duckdb-wasm

Rust

Rust는 Cargo로 추가해요. bundled 피처를 켜면 DuckDB의 C 라이브러리를 함께 컴파일해서, 별도의 시스템 라이브러리 없이 바로 쓸 수 있어서 편해요.

cargo add duckdb --features bundled

Go

Go 모듈로 가져오면 돼요.

go get github.com/duckdb/duckdb-go/v2

C / C++

C/C++에서는 DuckDB의 핵심 C API인 libduckdb 를 직접 받아 링크해요. 플랫폼별 라이브러리 zip을 아래에서 받을 수 있어요.

ODBC

Excel이나 Tableau 같은 BI 도구에서 DuckDB에 접속할 때는 ODBC 드라이버가 필요해요. 드라이버 zip은 GitHub Releases에서 받을 수 있어요 (버전별로 1.5.5.0, 1.4.5.0이 있어요).

설치 후 확인하기

설치가 끝났다면 터미널에서 duckdb라고 입력하고 Enter를 눌러보세요. duckdb 프롬프트가 나오면 설치가 잘 된 거예요. 바로 SELECT 42; 같은 쿼리를 입력해서 동작을 확인해 볼 수 있어요. 이제 프로세스 관리 없이 파일 하나만으로 데이터 분석을 시작할 수 있게 된 거예요.

더 자세한 설치 옵션과 각 클라이언트의 상세 사용법은 아래 공식 문서에서 확인할 수 있어요.