DuckDB 安装完全指南：从入门到实战

为什么我选择了 DuckDB？

说实话，在遇到 DuckDB 之前，我已经受够了数据分析的那些破事。

处理百万行 CSV 的时候，Pandas 慢得像蜗牛，等得我都想砸电脑。想装个 PostgreSQL 吧，又觉得大材小用，配置起来还麻烦。SQLite 倒是轻量，但做复杂查询的时候性能又跟不上。

直到有一天，我在 Hacker News 上看到有人提到 DuckDB，说它是"分析领域的 SQLite"。当时我还不以为然，心想又来一个吹牛的数据库。但抱着试试看的心态装了一下，结果直接被它的性能震撼到了——100万行数据聚合查询只要 0.212 秒。

我当时就惊呆了。同样的查询，Pandas 要跑 2-10 秒，DuckDB 只要 0.2 秒，这差距也太大了吧？

这篇文章，我想把安装过程中踩过的坑、测试过的性能数据，都分享给你们。毕竟当时我查资料的时候，也没找到这么详细的对比。

先说说我的测试环境

在开始之前，先交代一下我的测试环境，免得你们测试结果对不上：

项目	配置
操作系统	Ubuntu 24.04.4 LTS
Python	3.12.3
Node.js	v20.20.2
DuckDB	1.5.5
测试数据	100万行 IoT 传感器数据

测试数据我是从 Kaggle 上下载的，后面会给出链接。

安装方式一：Python（我最推荐的方式）

为什么我最推荐 Python？

不瞒你说，我一开始也纠结过用哪种方式安装。但试了一圈下来，Python 版本真的是最省心的：

安装就一行命令，简单粗暴
和 Pandas 无缝集成，之前的代码基本不用改
社区最活跃，遇到问题随便一搜就能找到答案

我的安装过程

第一步：创建虚拟环境

说实话，我当时也试过直接全局安装，结果把系统 Python 环境搞得一团糟。后来学乖了，每次都先用虚拟环境。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
python3 -m venv duckdb-env
source duckdb-env/bin/activate
```python

**第二步：安装 DuckDB**

```bash
pip install duckdb pandas pyarrow
```bash

这里我顺便把 pandas 和 pyarrow 也装了，后面测试要用。

**第三步：验证安装**

```python
import duckdb
print(f"DuckDB 版本: {duckdb.__version__}")
```python

输出：

```sql
DuckDB 版本: 1.5.5
```python

看到版本号的那一刻，我心里就踏实了——装成功了。

### 快速测试一下

```python
import duckdb

# 连接内存数据库
con = duckdb.connect()

# 基本查询
result = con.execute("SELECT 'Hello DuckDB' as msg, 42 as num").fetchdf()
print(result)
```sql

输出：

```text
          msg  num
0  Hello DuckDB   42
```text

就这么简单，一个查询就通了。

### 直接查询 CSV 文件（这个功能太香了）

这是 DuckDB 最让我惊艳的功能——**不需要导入数据，直接 SQL 查询文件**。

当时我看到这个功能的时候，第一反应是：这也太方便了吧？以前用 Pandas，还得先 `pd.read_csv()` 把数据加载进来，再处理。DuckDB 直接一条 SQL 就搞定了。

```python
# 直接查询 CSV
result = con.execute("""
    SELECT product, COUNT(*) as cnt 
    FROM 'large_ecommerce_orders.csv' 
    GROUP BY product 
    ORDER BY cnt DESC 
    LIMIT 3
""").fetchdf()

print(result)
```sql

输出：

```text
   product    cnt
0  Keyboard  10132
1     Phone  10122
2       RAM  10084
```text

看到结果的那一刻，我就知道，这个工具我用定了。

### 性能测试（这才是重头戏）

我用 100 万行 IoT 传感器数据做了聚合查询测试，结果如下：

```python
import time

start = time.time()
result = con.execute("""
    SELECT sensor_id, COUNT(*) as n, ROUND(AVG(value), 2) as avg_v 
    FROM 'iot_sensor_data.csv' 
    GROUP BY sensor_id 
    ORDER BY n DESC 
    LIMIT 5
""").fetchdf()

elapsed = time.time() - start
print(f"100万行聚合: {elapsed:.3f}秒")
print(result)
```text

输出：

```text
100万行聚合: 0.212秒

   sensor_id      n  avg_v
0  sensor_031  20362  24.91
1  sensor_043  20317  25.13
2  sensor_021  20243  24.97
3  sensor_002  20210  25.14
4  sensor_036  20202  25.02
```text

0.212 秒！我当时看到这个结果的时候，反复确认了好几遍，生怕是自己计时写错了。同样的查询，Pandas 要跑 2-10 秒，DuckDB 只要 0.2 秒，这差距也太明显了。

---

## 安装方式二：CLI（命令行版本）

### 我为什么要试 CLI？

说实话，CLI 版本我平时用得不多。但有一次在服务器上，Python 环境出了问题，临时需要用 DuckDB 救急，当时就靠 CLI 版本顶上的。从那以后，我就知道，CLI 版本必须得会装，关键时刻能救命。

### 安装过程

**第一步：下载 CLI**

```bash
# Linux (x86_64)
wget https://github.com/duckdb/duckdb/releases/download/v1.5.5/duckdb_cli-linux-amd64.zip
unzip duckdb_cli-linux-amd64.zip
chmod +x duckdb
```sql

这里有个坑我得说一下。我当时下载的时候，GitHub 老是超时，折腾了半天。后来开了代理才搞定。如果你在国内，建议直接用代理或者镜像。

**第二步：验证安装**

```bash
./duckdb --version
```bash

输出：

```sql
v1.5.5
```bash

**第三步：基本使用**

```bash
# 交互式模式
./duckdb

# 执行 SQL
echo "SELECT 'Hello DuckDB';" | ./duckdb

# 查询 CSV 文件
echo "SELECT * FROM 'data.csv' LIMIT 5;" | ./duckdb
```sql

### 我的使用感受

CLI 版本和 Python 版本功能完全一致，性能也一样。但它不支持 Pandas 集成，所以复杂分析还是得用 Python。CLI 更适合快速验证 SQL 语法，或者在服务器上做简单的查询。

---

## 安装方式三：Node.js

### 我为什么也测试了 Node.js？

其实 Node.js 版本我用得最少。但为了完整性，我还是测试了一下。毕竟有些 Web 项目可能需要用到。

### 安装过程

**第一步：安装 DuckDB**

```bash
npm install duckdb
```bash

**第二步：验证安装**

```javascript
const duckdb = require('duckdb');
const db = new duckdb.Database(':memory:');

db.all('SELECT 42 as answer', (err, res) => {
    if (err) console.error('Error:', err);
    else console.log('Node.js 查询结果:', res);
    db.close();
});
```sql

输出：

```text
Node.js 查询结果: [ { answer: 42 } ]
```bash

### 我的使用感受

Node.js 版本的 API 是异步的，用起来没有 Python 那么直观。而且文档也不如 Python 完善，遇到问题经常得去翻源码。如果不是 Web 项目必须用，我建议还是优先选 Python。

---

## 三种方式对比

| 维度 | Python | CLI | Node.js |
|------|--------|-----|---------|
| **安装难度** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **性能** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **生态集成** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **文档完善度** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
| **我的推荐场景** | 数据分析/ETL | 快速验证/脚本 | Web应用 |

---

## 我踩过的坑（血泪教训）

### 坑 1：虚拟环境问题

第一次安装的时候，我直接 `pip install duckdb`，结果报错 `externally-managed-environment`。当时就懵了，查了半天才知道 Ubuntu 24.04 默认不允许全局安装 Python 包。折腾了半小时才搞定，真是血泪教训。

**解决方案**：

```bash
# 方法 1：用虚拟环境（强烈推荐）
python3 -m venv myenv
source myenv/bin/activate
pip install duckdb

# 方法 2：强制安装（不推荐，我当时试过，系统环境差点崩溃）
pip install --break-system-packages duckdb
```python

### 坑 2：CLI 下载超时

下载 CLI 的时候，GitHub 老是超时。我试了好几次都失败了，后来开了代理才搞定。

**解决方案**：

```bash
# 方法 1：用代理
export https_proxy=http://127.0.0.1:7890
wget https://github.com/...

# 方法 2：用镜像
wget https://ghproxy.com/https://github.com/...

# 方法 3：用 Python 下载（更稳定，我当时就是用这个方法成功的）
python3 -c "import urllib.request; urllib.request.urlretrieve('URL', 'duckdb.zip')"
```python

### 坑 3：CSV 列名错误

查询 CSV 的时候，报错 `Column "price" not found`。我当时还以为是自己 SQL 写错了，检查了半天才发现，CSV 文件的列名和我想象的不一样。

**解决方案**：先查看列名

```python
# 查看 CSV 列名
result = con.execute("SELECT * FROM 'data.csv' LIMIT 1").fetchdf()
print(result.columns.tolist())
```text

---

## 我的下一步计划

装好 DuckDB 之后，我迫不及待地去试了试 Parquet 文件查询，速度比 CSV 还快。后来又试了试和 Pandas 的集成，简直是无缝衔接。

接下来，我打算深入研究一下 DuckDB 的 SQL 语法，看看它和标准 SQL 有什么不同。还有就是它的扩展功能，比如 HTTP 扩展、Spatial 扩展，听起来都很厉害。

如果你也在做数据分析，被性能问题折磨得够呛，真心建议试试 DuckDB。用了这一个月，我已经离不开它了。

---

## 参考资源

- [DuckDB 官方文档](https://duckdb.org/docs/)
- [DuckDB GitHub](https://github.com/duckdb/duckdb)
- [DuckDB Python API](https://duckdb.org/docs/api/python/)
- [DuckDB vs Pandas 性能对比](https://duckdb.org/2021/05/14/sql-on-pandas.html)

---

## 延伸阅读

- [DuckDB vs SQLite：选择哪个？](/p/duckdb-vs-sqlite/) - 小数据集 SQLite 快 153 倍，大数据集 DuckDB 快 3.38 倍
- [DuckDB 技术栈全解析](/p/duckdb-tech-stack/) - 列式存储、向量化执行引擎原理
- [DuckDB 内存模式 vs 持久化模式](/p/duckdb-memory-vs-persistent/) - 性能实测与选型指南


---

## 我的下一步计划

装好 DuckDB 之后，我迫不及待地去试了试 Parquet 文件查询，速度比 CSV 还快。后来又试了试和 Pandas 的集成，简直是无缝衔接。

接下来，我打算深入研究一下 DuckDB 的 SQL 语法，看看它和标准 SQL 有什么不同。还有就是它的扩展功能，比如 HTTP 扩展、Spatial 扩展，听起来都很厉害。

如果你也在做数据分析，被性能问题折磨得够呛，真心建议试试 DuckDB。用了这一个月，我已经离不开它了。

---

## 参考资源

- [DuckDB 官方文档](https://duckdb.org/docs/)
- [DuckDB GitHub](https://github.com/duckdb/duckdb)
- [DuckDB Python API](https://duckdb.org/docs/api/python/)
- [DuckDB vs Pandas 性能对比](https://duckdb.org/2021/05/14/sql-on-pandas.html)

---

## 延伸阅读

- [DuckDB vs SQLite：选择哪个？](/p/duckdb-vs-sqlite/) - 小数据集 SQLite 快 153 倍，大数据集 DuckDB 快 3.38 倍
- [DuckDB 技术栈全解析](/p/duckdb-tech-stack/) - 列式存储、向量化执行引擎原理
- [DuckDB 内存模式 vs 持久化模式](/p/duckdb-memory-vs-persistent/) - 性能实测与选型指南