---
title: "DuckDB UI vs DuckLocal: qual interface local do DuckDB usar"
description: "O DuckDB UI é um notebook de navegador; o DuckLocal é um workspace de desktop. Como eles diferem, quando escolher o DuckDB UI e como rodá-lo dentro do DuckLocal com CALL start_ui()."
language: "pt-BR"
---

# DuckDB UI vs DuckLocal: qual você deve usar?

Os dois colocam uma interface local sobre o DuckDB. Um é um notebook de navegador que qualquer processo DuckDB pode abrir; o outro é um workspace de desktop construído em torno dos seus arquivos. Eles atendem a necessidades diferentes, e você pode rodar um dentro do outro.

![DuckDB UI vs DuckLocal, com o pato do DuckLocal em um notebook](https://ducklocal.app/assets/blog/duckdb-ui-vs-ducklocal-cover.webp)

Em março de 2025, o DuckDB 1.2.1 chegou com o DuckDB UI: rode `duckdb -ui` e um notebook abre no seu navegador, apoiado pelo processo DuckDB na sua própria máquina. Desde então, a pergunta mais comum que recebo sobre o DuckLocal é alguma versão de *“por que não usar simplesmente o DuckDB UI?”*

É uma pergunta justa. As duas ferramentas rodam o DuckDB localmente, nenhuma precisa de um servidor que você gerencia, e ambas mantêm suas consultas e dados no seu computador. Mas elas partem de lugares diferentes, e essa diferença decide qual delas se encaixa em um determinado trabalho. Este artigo é minha tentativa honesta de expor isso — incluindo os casos em que eu mesmo recorreria ao DuckDB UI.

## 1. A resposta curta

| Se você… | Use |
| --- | --- |
| já trabalha na CLI do DuckDB ou em Python e quer uma visão visual daquela sessão | DuckDB UI |
| pensa em notebooks de células SQL | DuckDB UI |
| usa o MotherDuck ou quer compartilhar resultados por meio dele | DuckDB UI |
| parte de uma pilha de arquivos e pastas CSV, Parquet, JSON ou Excel | DuckLocal |
| precisa trabalhar offline, ou quer cada parte da ferramenta instalada e verificável | DuckLocal |
| quer gráficos e dashboards que você possa salvar como arquivos e manter no git | DuckLocal |
| quer que um agente de IA consulte os mesmos dados a partir de um terminal | DuckLocal |
| quer os dois sobre os mesmos dados | DuckLocal, depois `CALL start_ui();` |

## 2. O que é o DuckDB UI

O DuckDB UI é criado e mantido pela MotherDuck e entregue como uma extensão do DuckDB chamada `ui`. Você o inicia com `duckdb -ui` no terminal, ou com `CALL start_ui();` de qualquer cliente DuckDB — a CLI, Python, Java e assim por diante.

A extensão inicia um servidor HTTP em `localhost` (porta 4213 por padrão) dentro do processo DuckDB que a chamou, e abre seu navegador. Como a UI conversa com esse mesmo processo, ela vê tudo o que o processo vê: seus bancos anexados, sua memória e seus arquivos locais.

O que você tem no navegador:

- **Notebooks** — coleções nomeadas e salvas de células SQL, com destaque de sintaxe e autocomplete. Uma célula pode conter várias instruções.

- **Um navegador de bancos anexados** com um resumo de tabela: contagem de linhas, colunas, tipos e um perfil por coluna.

- **Um Column Explorer** que resume um resultado e permite aprofundar em cada coluna.

- **Login opcional no MotherDuck**, para persistir tabelas no data warehouse na nuvem do MotherDuck e compartilhá-las. É opt-in; por padrão, nada sai da sua máquina.

Dois detalhes importam para a comparação. Primeiro, o servidor local da extensão **busca os arquivos de frontend da própria UI em `https://ui.duckdb.org`** para que a interface fique atualizada; suas consultas continuam rodando localmente, mas a UI em si é carregada da rede. O uso offline não era suportado no lançamento. Segundo, a extensão tem licença MIT, enquanto no lançamento o código-fonte do frontend não era publicado.

Fontes: [anúncio do DuckDB UI](https://duckdb.org/2025/03/12/duckdb-ui) · [documentação da extensão UI](https://duckdb.org/docs/current/core_extensions/ui.html) · [duckdb/duckdb-ui no GitHub](https://github.com/duckdb/duckdb-ui). Confira-as para mudanças feitas depois que este artigo foi escrito.

## 3. Lado a lado

| Dimensão | DuckDB UI | DuckLocal |
| --- | --- | --- |
| O que é | Um notebook de navegador servido pela extensão `ui` do DuckDB | Um aplicativo de desktop nativo com o DuckDB embutido |
| Como iniciar | `duckdb -ui` ou `CALL start_ui();` de qualquer cliente DuckDB (1.2.1 ou posterior) | Abra o aplicativo, ou rode `ducklocal ./data/` |
| Onde as consultas rodam | No processo DuckDB que o iniciou, na sua máquina | No DuckDB embutido do DuckLocal, na sua máquina |
| Arquivos da interface | Buscados de `ui.duckdb.org` pelo servidor local | Vêm junto com o aplicativo |
| Offline | Precisa de rede para os arquivos da UI | Funciona offline; a rede é usada apenas para S3, tiles de mapa, instalação de extensões e verificações de atualização que você ativar |
| Trazer dados | SQL: `read_csv`, `ATTACH`, ou o que a sessão já tem | Arraste arquivos, pastas e padrões glob; eles viram views e continuam lá no próximo lançamento |
| Forma de trabalhar | Notebooks de células SQL | Abas de consulta, uma barra lateral de esquema, histórico, `EXPLAIN` e um profiler |
| Explorar resultados | Resumos de tabela e o Column Explorer | Grade de resultados, uma aba Overview por coluna e gráficos integrados |
| Reúso e compartilhamento | Notebooks salvos; compartilhamento opcional via MotherDuck | Dashboards `.dash` em texto puro que você pode revisar e manter no git, com comentários nos gráficos |
| Agentes de IA | Não é o foco | CLI `ducklocal` com JSON limitado e uma skill oficial para agentes |
| Código-fonte | Extensão sob MIT; frontend não publicado no lançamento | Apache-2.0, aplicativo e código no GitHub |
| Plataformas | Onde o DuckDB roda, exceto `windows_arm64` | macOS em Apple silicon, Windows x64, Linux x86_64 |

A forma mais curta de dizer isso: **o DuckDB UI é uma janela para uma sessão DuckDB que você já tem. O DuckLocal é a sessão, construída em torno dos arquivos que você quer examinar.**

## 4. Quando usar o DuckDB UI

### Você já vive no DuckDB

Se seu trabalho acontece na CLI do DuckDB ou em um script Python, a UI está a um comando de distância e não precisa de um novo aplicativo. Rode `duckdb -ui my.duckdb`, ou chame `start_ui()` a partir do processo Python que já carregou e transformou seus dados, e você está olhando exatamente para aquele estado. O DuckLocal não consegue ver dentro de outro processo; a UI é feita para isso.

### Você pensa em notebooks

Algumas análises são uma longa sequência de passos que você quer manter em ordem: carregar, limpar, juntar, verificar, resumir. Notebooks com células nomeadas e salvas se encaixam bem nisso, e uma célula pode rodar várias instruções de uma vez. As abas de consulta do DuckLocal são melhores para fazer muitas perguntas separadas do que para manter uma longa narrativa.

### Você usa o MotherDuck

Se sua equipe já compartilha dados por meio do MotherDuck, a UI é a interface natural: faça login e o mesmo notebook alcança tanto o DuckDB local quanto seu data warehouse na nuvem. O DuckLocal não tem serviço de nuvem e não planeja ter.

### O DuckLocal não tem build para a sua máquina

O DuckLocal é distribuído para macOS em Apple silicon, Windows x64 e Linux x86_64. Em um Mac Intel, por exemplo, você teria que compilar o DuckLocal a partir do código-fonte, enquanto o DuckDB UI roda em qualquer lugar onde o DuckDB roda (exceto Windows em ARM).

## 5. Quando usar o DuckLocal

### Você começa pelos arquivos, não pelo SQL

Arraste um CSV, uma pasta de arquivos Parquet ou um padrão como `./logs/2026-*/*.json`, e cada um vira uma view que você pode consultar, com suas colunas na barra lateral. Cada planilha não vazia de uma pasta de trabalho do Excel vira uma tabela. Nada precisa ser escrito como `read_csv(…)` primeiro, e os arquivos continuam lá na próxima vez que você abrir o aplicativo.

### Você precisa que funcione offline, ou que seja totalmente verificável

A interface do DuckLocal faz parte do aplicativo que você instalou. Ela não carrega código de interface em tempo de execução, não baixa extensões por conta própria, e as verificações de atualização ficam desligadas até você ativá-las. O frontend do DuckDB UI, por outro lado, é buscado quando a UI inicia, e ela pode ler os dados carregados no DuckDB — a própria documentação do DuckDB recomenda apontá-la apenas para uma URL em que você confia. Para a maioria das pessoas, isso está bem. Para revisões de segurança, auditorias, dados regulados ou máquinas isoladas, “tudo está instalado e é de código aberto” é a garantia mais forte.

### Você quer gráficos e dashboards como arquivos

Os resultados viram gráficos de barras, linhas, dispersão, pizza e mapas ali mesmo. Quando uma visualização vale a pena manter, um [arquivo `.dash`](https://ducklocal.app/docs/pt/dashboards) descreve suas consultas, gráficos e filtros como texto puro — algo que você pode comparar com diff, revisar em um pull request e validar com `ducklocal check`.

### Você trabalha com um agente de IA

A [CLI `ducklocal`](https://ducklocal.app/pt/use-cases/ai-agent-sql/) oferece a um agente um fluxo de SQL schema-first, com uma instrução por vez e saída JSON limitada, e os comentários em dashboards permitem entregar a ele uma pergunta sobre um gráfico específico. Os mesmos arquivos estão abertos no aplicativo para você conferir o trabalho dele.

## 6. Rode o DuckDB UI dentro do DuckLocal

Você não precisa escolher. O DuckDB UI é uma extensão, e o DuckLocal consegue carregar extensões do DuckDB — então a UI roda sobre a própria instância DuckDB do DuckLocal:

- Abra a aba **Extensions** na barra lateral do DuckLocal.

- Clique em **Install** na linha `ui` e depois em **Load**. O DuckLocal nunca instala extensões por conta própria, então esse passo é deliberado.

- Em uma aba de consulta, rode:

```text
CALL start_ui();
```

Seu navegador abre o DuckDB UI em `http://localhost:4213`. Ele está anexado à instância DuckDB que o DuckLocal está executando, então os arquivos que você abriu no DuckLocal estão lá para usar em um notebook.

![Aba Extensions do DuckLocal com a extensão ui marcada como Loaded, ao lado da tela inicial Drop your data in](https://ducklocal.app/assets/blog/ducklocal-extensions-ui.webp)

*A extensão `ui` carregada na aba Extensions do DuckLocal. A partir daqui, `CALL start_ui();` abre o DuckDB UI na mesma instância DuckDB.*

Algumas coisas que vale saber:

- **Precisa de rede:** uma vez para instalar `ui`, e a cada inicialização, para buscar os arquivos da UI em `ui.duckdb.org`.

- **Termina com o DuckLocal.** Sair do DuckLocal fecha sua instância DuckDB e o servidor da UI junto. `CALL stop_ui_server();` o encerra antes, e `CALL start_ui_server();` o inicia sem abrir um navegador.

- **Os notebooks pertencem à extensão,** armazenados em `~/.duckdb/extension_data/ui/`. O histórico de consultas do DuckLocal não inclui o que você roda na UI.

- **Não é possível rodar diretamente em um banco somente leitura.** Anexe esse banco a partir de um notebook com `ATTACH '…' (READ_ONLY)`.

É assim que eu uso os dois juntos: o DuckLocal para abrir os dados, olhar as colunas e gerar gráficos para as perguntas óbvias; o DuckDB UI quando uma pergunta se transforma em uma investigação mais longa que quero manter como notebook.

Documentação: [Abrir o DuckDB UI a partir do DuckLocal](https://ducklocal.app/docs/pt/schema-and-history#duckdb-ui) · [Aba Extensions](https://ducklocal.app/docs/pt/schema-and-history#extensions)

## 7. FAQ

### Qual é a diferença entre o DuckDB UI e o DuckLocal?

O DuckDB UI é um notebook de navegador servido pela extensão `ui` do DuckDB a partir de qualquer processo DuckDB que o inicie. O DuckLocal é um aplicativo de desktop nativo com o DuckDB embutido, construído em torno de abrir arquivos e pastas, gráficos, dashboards em texto puro e uma CLI para agentes de IA. Ambos rodam consultas localmente.

### O DuckLocal substitui o DuckDB UI?

Não. Eles se sobrepõem ao rodar SQL em dados locais, mas a UI é melhor como janela para uma sessão DuckDB existente, e o DuckLocal como workspace para arquivos. Como a UI roda dentro do DuckLocal, você pode usar os dois.

### O DuckDB UI funciona offline?

Suas consultas rodam localmente, mas os arquivos de frontend da UI são buscados em `ui.duckdb.org` a cada inicialização, então ela precisa de acesso à rede. A interface do DuckLocal vem junto com o aplicativo e funciona offline.

### Minhas consultas vão para o MotherDuck?

Não, a menos que você faça login no MotherDuck na UI. Por padrão, o DuckDB UI roda suas consultas na sua própria máquina, assim como o DuckLocal.

## Links relacionados

- [A UI local do DuckDB (blog do DuckDB)](https://duckdb.org/2025/03/12/duckdb-ui)

- [Documentação da extensão UI](https://duckdb.org/docs/current/core_extensions/ui.html)

- [Análise de dados local com o DuckLocal](https://ducklocal.app/pt/use-cases/local-data-analysis/)

- [O que o Claude Dashboards me ensinou sobre o DuckLocal](https://ducklocal.app/pt/blog/claude-dashboards-ducklocal/)

[← Todos os posts](https://ducklocal.app/pt/blog/)

Source: https://ducklocal.app/pt/blog/duckdb-ui-vs-ducklocal/
