DuckDB 安装概述
DuckDB 是一个轻量级的嵌入式分析数据库，安装过程极其简单——不需要配置服务器、不需要管理用户权限、不需要复杂的依赖环境。本文提供 Windows / macOS / Linux / Python / Docker 全平台的 DuckDB 安装使用指南。
DuckDB 提供三种主要的安装方式：
- CLI 命令行工具 — 直接下载可执行文件，秒级启动
- Python 包 —
pip install duckdb，数据分析最常用 - Docker 镜像 — 适合容器化部署和 CI/CD 环境
无论你选择哪种方式，DuckDB 的安装使用都遵循"下载即用"的原则。
Windows 平台 DuckDB 安装使用
方法一：直接下载 EXE（推荐）
从 DuckDB 官网下载 Windows 版 CLI：
# 访问 https://duckdb.org/download/
# 选择 Windows 版本，下载 duckdb_cli-windows-amd64.zip
# 解压后得到 duckdb.exe，双击或命令行运行
验证安装：
duckdb --version
# v1.2.0
方法二：使用 winget
winget install DuckDB.cli
方法三：通过 Python 安装
pip install duckdb duckdb-cli
安装完成后，在命令行输入 duckdb 即可进入交互式 Shell。
Windows 环境配置建议
- 将 duckdb.exe 所在目录添加到 PATH 环境变量，方便全局调用
- 使用 Windows Terminal 或 PowerShell 获得更好的命令行体验
- 处理大型 Parquet 文件时，建议使用 64 位系统
macOS 平台 DuckDB 安装使用
方法一：Homebrew（推荐）
brew install duckdb
# 验证安装
duckdb --version
方法二：直接下载
从官网下载 macOS 版本，支持 Intel 和 Apple Silicon (ARM) 两种架构。
# 下载后解压即可使用
tar -xzf duckdb_cli-osx-universal.zip
./duckdb
macOS 安装注意事项
- Apple Silicon (M1/M2/M3/M4) 用户选择 ARM 版本获得最佳性能
- 可以通过
brew upgrade duckdb随时更新到最新版本 - 配合 iTerm2 终端使用效果更佳
Linux 平台 DuckDB 安装使用
方法一：一行脚本安装（推荐）
curl -sL https://install.duckdb.org | sh
方法二：apt 安装（Debian/Ubuntu）
sudo apt update
sudo apt install duckdb
方法三：手动下载二进制
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/
方法四：从源码编译
git clone https://github.com/duckdb/duckdb.git
cd duckdb
make
# 编译后的二进制在 build/release/duckdb
Python 环境 DuckDB 安装使用
基础安装
pip install duckdb
安装后验证
import duckdb
# 检查版本
print(duckdb.__version__)
# 第一个查询
result = duckdb.sql("SELECT 'DuckDB is running!' AS status")
print(result)
推荐安装扩展
pip install duckdb duckdb-cli # CLI 工具
pip install jupysql # Jupyter 集成
Python 环境的 DuckDB 使用场景
import duckdb
import pandas as pd
# 1. 创建持久化数据库
con = duckdb.connect('my_analysis.duckdb')
# 2. 直接从 CSV 加载数据
con.sql("CREATE TABLE sales AS SELECT * FROM read_csv_auto('sales_2026.csv')")
# 3. 与 Pandas 无缝互操作
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 安装使用
拉取镜像并运行
# 官方镜像
docker pull duckdb/duckdb
# 交互式运行
docker run -it --rm duckdb/duckdb
# 挂载数据卷
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 使用示例
# 在 Docker 中查询文件
docker run --rm -v $(pwd):/workspace duckdb/duckdb \
-c "SELECT count(*) FROM '/workspace/data.csv'"
各平台安装对比总结
| 平台 | 推荐方式 | 安装时间 | 文件大小 |
|---|---|---|---|
| Windows | 下载 EXE | 1 分钟 | ~25MB |
| macOS | Homebrew | 2 分钟 | ~30MB |
| Linux | 一键脚本 | 1 分钟 | ~25MB |
| Python | pip install | 30 秒 | ~15MB |
| Docker | docker pull | 1 分钟 | ~80MB |
常见安装问题排查
1. 命令行找不到 duckdb
# Windows: 检查 PATH 环境变量是否包含 duckdb.exe 所在目录
# macOS/Linux: 检查是否在 /usr/local/bin 中
which duckdb # 确认路径
2. Python 导入失败
# 确保在正确的虚拟环境中安装
pip list | grep duckdb
# 如果看不到，重新安装
pip install --upgrade duckdb
3. 权限问题
# Linux/macOS: sudo 安装到系统目录
sudo cp duckdb /usr/local/bin/
# 或者安装到用户目录
mkdir -p ~/.local/bin
cp duckdb ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"
相关文章
📘 博客: https://duckdblab.org #DuckDB #安装使用 #安装教程 #数据分析