DuckDB Installation Overview
DuckDB is a lightweight embedded analytical database with an incredibly simple installation process — no server configuration, no user management, no complex dependencies. This guide covers Windows / macOS / Linux / Python / Docker platform installation and usage.
DuckDB offers three main installation methods:
- CLI binary — Download a single executable, ready in seconds
- Python package —
pip install duckdb, most common for data analysis - Docker image — Perfect for containerized deployments and CI/CD
No matter which platform you choose, DuckDB installation follows a “download and run” philosophy.
Windows DuckDB Installation and Usage
Method 1: Direct EXE Download (Recommended)
Download the Windows CLI from the DuckDB website:
# Visit https://duckdb.org/download/
# Select Windows version, download duckdb_cli-windows-amd64.zip
# Unzip → run duckdb.exe from command line
Verify installation:
duckdb --version
# v1.2.0
Method 2: Using winget
winget install DuckDB.cli
Method 3: Via Python
pip install duckdb duckdb-cli
Windows Tips
- Add the duckdb.exe directory to your PATH for global access
- Use Windows Terminal or PowerShell for the best CLI experience
- A 64-bit system is recommended for large Parquet file processing
- Windows Subsystem for Linux (WSL) users can also install DuckDB via the Linux method inside WSL
macOS DuckDB Installation and Usage
Method 1: Homebrew (Recommended)
brew install duckdb
# Verify
duckdb --version
Method 2: Direct Download
Download from the official website — supports both Intel and Apple Silicon (ARM).
tar -xzf duckdb_cli-osx-universal.zip
./duckdb
macOS Tips
- Apple Silicon (M1/M2/M3/M4) users should choose the ARM build for best performance
- Update to the latest version with
brew upgrade duckdb
Linux DuckDB Installation and Usage
Method 1: One-Line Script (Recommended)
curl -sL https://install.duckdb.org | sh
Method 2: apt Install (Debian/Ubuntu)
sudo apt update
sudo apt install duckdb
Method 3: Manual Binary Download
wget https://github.com/duckdb/duckdb/releases/download/v1.2.0/duckdb_cli-linux-amd64.zip
unzip duckdb_cli-linux-amd64.zip
chmod +x duckdb
sudo mv duckdb /usr/local/bin/
Method 4: Build from Source
git clone https://github.com/duckdb/duckdb.git
cd duckdb
make
# Binary at build/release/duckdb
Python DuckDB Installation and Usage
Basic Installation
pip install duckdb
Verify
import duckdb
print(duckdb.__version__)
result = duckdb.sql("SELECT 'DuckDB is running!' AS status")
print(result)
Real-World Python Usage
import duckdb
import pandas as pd
# 1. Create a persistent database
con = duckdb.connect('my_analysis.duckdb')
# 2. Load CSV data directly
con.sql("CREATE TABLE sales AS SELECT * FROM read_csv_auto('sales_2026.csv')")
# 3. Seamless Pandas interop
df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})
result = con.sql("SELECT x, y, x + y AS sum FROM df")
print(result)
Docker DuckDB Installation and Usage
Pull and Run
# Official image
docker pull duckdb/duckdb
# Interactive mode
docker run -it --rm duckdb/duckdb
# Mount data volume
docker run -it --rm -v $(pwd)/data:/data duckdb/duckdb
Docker Compose
version: '3'
services:
duckdb:
image: duckdb/duckdb:latest
volumes:
- ./data:/data
stdin_open: true
tty: true
Docker Query Example
docker run --rm -v $(pwd):/workspace duckdb/duckdb \
-c "SELECT count(*) FROM '/workspace/data.csv'"
Post-Installation: Verify Everything Works
After installing DuckDB on any platform, run these checks to confirm your setup is correct:
Check 1: CLI Version
duckdb --version
# Expected output: v1.2.0 (or newer)
Check 2: Run a Test Query
# DuckDB accepts SQL directly from the command line with -c
duckdb -c "SELECT 'Installation successful!' AS message, version() AS duckdb_version"
Check 3: File Persistence Test
# Create a database, insert data, then verify it persists
duckdb test_persist.duckdb -c "
CREATE TABLE test AS SELECT 'hello' AS greeting;
SELECT * FROM test;
"
# Re-open and verify data is still there
duckdb test_persist.duckdb -c "SELECT * FROM test;"
# Should still return: hello
Check 4: MotherDuck Integration (Optional)
If you plan to use DuckDB with cloud synchronization, also install the MotherDuck extension:
duckdb -c "INSTALL motherduck; LOAD motherduck;"
Once these four checks pass, your DuckDB installation is fully operational and ready for analytical workloads.
Quick Start After Installation
Once DuckDB is installed, here’s a 30-second smoke test to confirm everything works end-to-end:
# Launch DuckDB in-memory mode
duckdb
# Inside the DuckDB CLI, type:
SELECT 'DuckDB is ready' AS status;
# Query a CSV file directly (no import needed):
SELECT count(*) FROM read_csv_auto('https://raw.githubusercontent.com/duckdb/duckdb/main/data/csv/titanic.csv');
If you see query results, your DuckDB installation and usage pipeline is fully operational. You’re now ready to analyze data at unprecedented speed.
Platform Comparison Summary
| Platform | Recommended Method | Install Time | Size |
|---|---|---|---|
| Windows | Download EXE | ~1 minute | ~25MB |
| macOS | Homebrew | ~2 minutes | ~30MB |
| Linux | One-line script | ~1 minute | ~25MB |
| Python | pip install | ~30 seconds | ~15MB |
| Docker | docker pull | ~1 minute | ~80MB |
Common Installation Issues
1. Command Not Found
# Check if duckdb is in your PATH
which duckdb
2. Python Import Error
# Ensure you're in the correct virtual environment
pip list | grep duckdb
# Reinstall if missing
pip install --upgrade duckdb
3. Permission Issues
# Linux/macOS: install with sudo
sudo cp duckdb /usr/local/bin/
# Or install to user directory
mkdir -p ~/.local/bin
cp duckdb ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"
Related Articles
- DuckDB Beginners Guide 2026
- DuckDB SQL Syntax Quick Reference
- DuckDB Source Code: Architecture & Key Modules
📘 Blog: https://duckdblab.org #DuckDB #Installation #Setup #Database