Skip to main content

Installing DuckDB

Learning Focus

Use this lesson to get DuckDB installed and running on your system across multiple environments.

Installation Methods​

Method 1: CLI Binary (Linux/macOS)​

# Download latest release (Linux x86_64)
curl -fsSL https://github.com/duckdb/duckdb/releases/latest/download/duckdb_cli-linux-amd64.zip -o duckdb.zip
unzip duckdb.zip
chmod +x duckdb
sudo mv duckdb /usr/local/bin/

# Verify installation
duckdb --version
# macOS via Homebrew
brew install duckdb

# Verify
duckdb --version

Method 2: Python Package​

pip install duckdb

# Verify in Python
python -c "import duckdb; print(duckdb.__version__)"

Method 3: Docker​

docker run -it --rm \
  -v $(pwd)/data:/data \
  datacatering/duckdb:latest \
  duckdb /data/mydb.db

Method 4: Node.js​

npm install duckdb

# Verify
node -e "const db = require('duckdb'); console.log('DuckDB loaded');"

Post-Installation Setup​

# Open an in-memory DuckDB session
duckdb

# Open or create a persistent database file
duckdb my_database.db

# Run a quick test
SELECT 42 AS answer, 'DuckDB is running' AS message;

Expected Output:

┌────────┬────────────────────┐
│ answer │      message       │
│ int32  │      varchar       │
├────────┼────────────────────┤
│     42 │ DuckDB is running  │
└────────┴────────────────────┘

Python Integration Setup​

import duckdb

# In-memory database
con = duckdb.connect()

# Persistent database
con = duckdb.connect("my_database.db")

# Run a query
result = con.execute("SELECT 42 AS answer").fetchall()
print(result)  # [(42,)]

Common Installation Issues​

Issue 1: Command Not Found​

duckdb: command not found

Solution: Ensure /usr/local/bin is in your $PATH:

export PATH="$PATH:/usr/local/bin"
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc

Issue 2: Python Version Mismatch​

ERROR: Could not find a version that satisfies the requirement duckdb

Solution: DuckDB requires Python 3.7+. Check your version:

python --version
pip install --upgrade pip
pip install duckdb

Issue 3: Permission Denied on Binary​

Permission denied: ./duckdb

Solution:

chmod +x ./duckdb

Best Practices​

  • Use persistent files (duckdb mydb.db) for work you want to save
  • Use in-memory (duckdb with no args) for quick exploratory queries
  • Install the Python package if you plan to use DuckDB inside notebooks or scripts

Common Pitfalls​

PitfallConsequencePrevention
Using in-memory without savingData lost when session closesUse duckdb mydb.db for persistent work
Installing outdated DuckDBMissing new featuresCheck duckdb --version and update regularly
Mixing Python 2 and 3 environmentsPackage not foundUse virtual environments (venv or conda)

Quick Reference​

# Install (Linux)
curl -fsSL https://github.com/duckdb/duckdb/releases/latest/download/duckdb_cli-linux-amd64.zip -o d.zip && unzip d.zip && sudo mv duckdb /usr/local/bin/

# Install (macOS)
brew install duckdb

# Install (Python)
pip install duckdb

# Start CLI
duckdb              # in-memory
duckdb mydb.db      # persistent

What's Next​