DuckDB UI 与 DuckLocal：该用哪一个？

1. 简短结论

2. DuckDB UI 是什么

DuckDB UI 由 MotherDuck 开发和维护，以一个名为 ui 的 DuckDB 扩展形式提供。可以在终端运行 duckdb -ui 启动，也可以在任何 DuckDB 客户端（CLI、Python、Java 等）里执行 CALL start_ui();。

扩展会在调用它的 DuckDB 进程内，于 localhost 上启动一个 HTTP 服务（默认端口 4213），并打开浏览器。由于 UI 直接与这个进程通信，它能看到这个进程能看到的一切：已附加的数据库、内存中的数据和本地文件。

你在浏览器里得到的是：

• Notebook——有名字、会被保存的 SQL 单元格集合，带语法高亮和自动补全。一个单元格可以包含多条语句。
• 已附加数据库的浏览器，以及表摘要：行数、列、类型和逐列概况。
• Column Explorer，汇总查询结果，并可以深入查看每一列。
• 可选的 MotherDuck 登录，用来把表持久化到 MotherDuck 的云数据仓库并共享。这需要主动选择；默认情况下，没有任何东西离开你的电脑。

有两个细节对这次对比很重要。第一，扩展的本地服务会从 https://ui.duckdb.org 拉取 UI 自身的前端文件，以保持界面最新；查询仍在本地执行，但界面本身是从网络加载的，UI 发布时也不支持离线使用。第二，扩展采用 MIT 许可，而发布时前端的源代码并未公开。

资料来源：DuckDB UI 发布文章 · UI 扩展文档 · GitHub 上的 duckdb/duckdb-ui。本文写成之后的变化，请以这些资料为准。

3. 逐项对比

用一句话概括：DuckDB UI 是一扇窗，让你看到已有的 DuckDB 会话；DuckLocal 本身就是那个会话，并且围绕你想看的文件来构建。

4. 什么时候该用 DuckDB UI

你本来就在 DuckDB 里工作

如果你的工作发生在 DuckDB CLI 或 Python 脚本里，UI 只差一条命令，不需要安装新应用。运行 duckdb -ui my.duckdb，或者在已经加载并处理好数据的 Python 进程里调用 start_ui()，你看到的就是那个状态本身。DuckLocal 看不到别的进程内部，而 UI 正是为此设计的。

你习惯用 Notebook 思考

有些分析是一长串要按顺序保留的步骤：加载、清洗、连接、检查、汇总。有名字、会被保存的单元格很适合这种工作，一个单元格还能一次执行多条语句。DuckLocal 的查询标签页更适合提出很多相互独立的问题，而不是保留一条很长的分析脉络。

你在用 MotherDuck

如果团队已经通过 MotherDuck 共享数据，UI 就是自然的前端：登录之后，同一个 Notebook 既能访问本地 DuckDB，也能访问云端数据仓库。DuckLocal 没有云服务，也不打算做。

DuckLocal 没有你机器的安装包

DuckLocal 提供 Apple 芯片的 macOS、Windows x64 和 Linux x86_64 版本。比如在 Intel Mac 上，你需要从源码构建 DuckLocal，而 DuckDB UI 在 DuckDB 能运行的地方都能用（ARM 版 Windows 除外）。

5. 什么时候该用 DuckLocal

你从文件出发，而不是从 SQL 出发

拖入一个 CSV、一个装满 Parquet 文件的文件夹，或者 ./logs/2026-*/*.json 这样的模式，每一个都会成为可以查询的视图，列显示在侧栏里。Excel 工作簿中每个非空工作表都会成为一张表。不需要先写 read_csv(…)，下次打开应用时文件也都还在。

你需要离线工作，或需要完全可审查

DuckLocal 的界面就是你安装的应用的一部分：它不在运行时加载界面代码，不会自行下载扩展，更新检查在你开启之前也是关闭的。相比之下，DuckDB UI 的前端在启动时才拉取，并且能读取加载到 DuckDB 中的数据——DuckDB 文档自己也建议只把它指向你信任的地址。对大多数人来说这没有问题；但对安全审查、审计、受监管数据或隔离网络中的机器来说，“所有部分都已安装且开源”是更有力的保证。

你想把图表和仪表盘存成文件

查询结果可以直接变成柱状图、折线图、散点图、饼图和地图。值得保留的视图，可以用 .dash 文件以纯文本描述其中的查询、图表和筛选——可以 diff、可以在 Pull Request 里审阅，也可以用 ducklocal check 校验。

你和 AI 智能体一起工作

ducklocal CLI 给智能体一套先看表结构、一次一条 SQL 的工作流，输出有边界的 JSON；仪表盘评论则让你可以就某一张具体的图表把问题交给它。同样的文件也在应用里打开着，方便你检查它的结果。

6. 在 DuckLocal 里运行 DuckDB UI

其实不必二选一。DuckDB UI 是一个扩展，而 DuckLocal 可以加载 DuckDB 扩展——所以 UI 可以直接运行在 DuckLocal 自己的 DuckDB 实例上：

1. 打开 DuckLocal 侧栏的 扩展 标签页。
2. 在 ui 一行点击 安装，再点击 加载。DuckLocal 从不自行安装扩展，所以这一步需要你主动完成。
3. 在查询标签页里运行：

CALL start_ui();

浏览器会在 http://localhost:4213 打开 DuckDB UI。它连接的是 DuckLocal 正在运行的 DuckDB 实例，所以你在 DuckLocal 里打开的文件，可以直接在 Notebook 中使用。

有几点值得了解：

• 它需要联网：安装 ui 时需要一次；之后每次启动，都要从 ui.duckdb.org 拉取界面文件。
• 它随 DuckLocal 一起结束。退出 DuckLocal 会关闭它的 DuckDB 实例，UI 服务也随之停止。CALL stop_ui_server(); 可以提前停止，CALL start_ui_server(); 则只启动服务、不打开浏览器。
• Notebook 属于扩展，保存在 ~/.duckdb/extension_data/ui/。在 UI 里执行的查询不会出现在 DuckLocal 的查询历史中。
• 它不能直接运行在只读数据库上。可以在 Notebook 里用 ATTACH '…' (READ_ONLY) 附加那个数据库。

我自己是这样搭配使用的：用 DuckLocal 打开数据、查看列、把显而易见的问题画成图；当某个问题演变成一段想保存成 Notebook 的较长调查时，再打开 DuckDB UI。

相关文档：在 DuckLocal 中打开 DuckDB UI · 扩展标签页

7. 常见问题

DuckDB UI 和 DuckLocal 有什么区别？

DuckDB UI 是由 DuckDB 的 ui 扩展提供的浏览器 Notebook，运行在启动它的那个 DuckDB 进程上。DuckLocal 是内置 DuckDB 的原生桌面应用，围绕打开文件和文件夹、图表、纯文本仪表盘以及面向 AI 智能体的 CLI 构建。两者的查询都在本地执行。

DuckLocal 是 DuckDB UI 的替代品吗？

不是。两者在“对本地数据运行 SQL”上有重叠，但 UI 最适合作为已有 DuckDB 会话的窗口，DuckLocal 最适合作为处理文件的工作台。既然 UI 能在 DuckLocal 里运行，你完全可以两个都用。

DuckDB UI 能离线使用吗？

查询在本地执行，但 UI 的前端文件每次启动都要从 ui.duckdb.org 拉取，所以需要联网。DuckLocal 的界面随应用一起安装，可以离线使用。

我的查询会发送到 MotherDuck 吗？

除非你在 UI 里登录 MotherDuck，否则不会。默认情况下，DuckDB UI 和 DuckLocal 一样，都在你自己的电脑上执行查询。