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ãoDuckDB UI
pensa em notebooks de células SQLDuckDB UI
usa o MotherDuck ou quer compartilhar resultados por meio deleDuckDB UI
parte de uma pilha de arquivos e pastas CSV, Parquet, JSON ou ExcelDuckLocal
precisa trabalhar offline, ou quer cada parte da ferramenta instalada e verificávelDuckLocal
quer gráficos e dashboards que você possa salvar como arquivos e manter no gitDuckLocal
quer que um agente de IA consulte os mesmos dados a partir de um terminalDuckLocal
quer os dois sobre os mesmos dadosDuckLocal, 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 · documentação da extensão UI · duckdb/duckdb-ui no GitHub. Confira-as para mudanças feitas depois que este artigo foi escrito.

3. Lado a lado

DimensãoDuckDB UIDuckLocal
O que éUm notebook de navegador servido pela extensão ui do DuckDBUm aplicativo de desktop nativo com o DuckDB embutido
Como iniciarduckdb -ui ou CALL start_ui(); de qualquer cliente DuckDB (1.2.1 ou posterior)Abra o aplicativo, ou rode ducklocal ./data/
Onde as consultas rodamNo processo DuckDB que o iniciou, na sua máquinaNo DuckDB embutido do DuckLocal, na sua máquina
Arquivos da interfaceBuscados de ui.duckdb.org pelo servidor localVêm junto com o aplicativo
OfflinePrecisa de rede para os arquivos da UIFunciona 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 dadosSQL: read_csv, ATTACH, ou o que a sessão já temArraste arquivos, pastas e padrões glob; eles viram views e continuam lá no próximo lançamento
Forma de trabalharNotebooks de células SQLAbas de consulta, uma barra lateral de esquema, histórico, EXPLAIN e um profiler
Explorar resultadosResumos de tabela e o Column ExplorerGrade de resultados, uma aba Overview por coluna e gráficos integrados
Reúso e compartilhamentoNotebooks salvos; compartilhamento opcional via MotherDuckDashboards .dash em texto puro que você pode revisar e manter no git, com comentários nos gráficos
Agentes de IANão é o focoCLI ducklocal com JSON limitado e uma skill oficial para agentes
Código-fonteExtensão sob MIT; frontend não publicado no lançamentoApache-2.0, aplicativo e código no GitHub
PlataformasOnde o DuckDB roda, exceto windows_arm64macOS 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 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 ducklocal CLI 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:

  1. Abra a aba Extensions na barra lateral do DuckLocal.
  2. 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.
  3. Em uma aba de consulta, rode:
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
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 · Aba 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

← Todos os posts