# Primeiros passos

> Instale o DuckLocal no macOS, Windows ou Linux, adicione a CLI ducklocal, abra um arquivo CSV, Parquet, JSON ou Excel e execute sua primeira consulta SQL no DuckDB.

Source: https://ducklocal.app/docs/pt/getting-started

O DuckLocal é um app de desktop para fazer perguntas com SQL aos arquivos de
dados da sua máquina. Não há servidor para rodar, nem conexão para configurar,
nem conta — você aponta para arquivos e começa a consultar. Esta página leva
você do download ao primeiro resultado em cerca de cinco minutos.

## 1. Instale {#install}

O DuckLocal roda no macOS, Windows e Linux. Os links abaixo baixam a versão mais
recente de `dl.ducklocal.app`; os mesmos arquivos e notas de versão estão no
[GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest).

Estes guias estão atualizados para a [v0.4.1](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.1), lançada em 15 de novembro de 2026. A versão 0.4.0 adicionou [fluxos de trabalho com agentes](agent-workflows.md): SQL restrito, uma transferência verificada para a janela, propostas de painel, registros de análise e projetos portáveis. A versão 0.4.1 adiciona filtros de seleção múltipla, um fuso horário e um gráfico de linha do tempo para painéis, blocos `view` que guardam o SQL compartilhado uma única vez, extensões da comunidade como `mssql` na aba Extensões, e um aviso para salvar tabelas criadas no banco de dados em memória. Se você está atualizando de uma versão anterior à 0.3.0, reinstale suas extensões: aquela versão moveu o DuckLocal para o DuckDB 2.0.

### Mac

Você precisa de **macOS 12 ou mais recente em Apple silicon** (M1 ou mais novo).

1. Baixe [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg).
2. Abra e arraste **DuckLocal** para **Aplicativos**.
3. Inicie o DuckLocal a partir de Aplicativos ou do Spotlight.

A imagem de disco é assinada e notarizada pela Apple, então abre sem nenhum
contorno para o Gatekeeper.

### Windows

Você precisa de **Windows 10 de 64 bits ou mais recente**.

1. Baixe [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) e extraia.
2. Execute `ducklocal.exe` da pasta extraída. A compilação ainda não tem
   assinatura de código, então o primeiro início pode mostrar **O Windows
   protegeu seu PC** — escolha **Mais informações** e depois **Executar assim
   mesmo**.

### Linux

Você precisa de um sistema **x86_64** com **glibc 2.35 ou mais recente** (Ubuntu 22.04,
Debian 12, Fedora 36 ou mais recente) e drivers gráficos com suporte a Vulkan.

```bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
```

::: details Compilando a partir do código-fonte
Você precisa de Rust estável 1.85.1 ou mais recente e um toolchain de C++
(Xcode Command Line Tools). O DuckDB é compilado a partir de fontes incluídas,
então a primeira compilação leva vários minutos e alguns gigabytes de disco.

```bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal
```

O binário é `./target/release/ducklocal`; use-o onde este guia diz
`ducklocal`. Veja [Desenvolvimento](development.md) para empacotar um `.app`.
:::

## 2. Adicione o comando `ducklocal` (opcional) {#add-command}

Tudo no app funciona sem terminal. Se você também quiser abrir dados pela
linha de comando — ou deixar um agente de IA analisá-los com a
[CLI](cli.md) — adicione o comando pelo app:

1. Clique no botão do robô na barra de título, ou escolha
   **DuckLocal → Linha de comando e IA…** na barra de menus.
2. Clique em **Instalar comando**. No Mac, o sistema pede sua senha para
   escrever em `/usr/local/bin`.
3. Abra um terminal novo e verifique: `ducklocal --version`.

O comando é um link para o app, então atualizar o DuckLocal atualiza o comando
também. Para atualizar, clique na versão no extremo direito da barra de status:
uma versão mais recente é baixada e instalada quando você reiniciar (veja
[Verificação de atualizações](settings-and-data.md#update-check)). Ele fica em `/usr/local/bin` no Mac e em `~/.local/bin` no Linux; no
Windows, a pasta do app é adicionada ao seu `Path`.

Na mesma caixa de diálogo, **Adicionar ao Claude Code** instala a skill do DuckLocal para que
o Claude Code saiba consultar seus arquivos, e **Copiar resumo** copia uma explicação curta
para colar em qualquer outro agente de IA. Veja
[CLI de IA e skill oficial](cli.md#install-the-official-skill).

::: details Adicionando manualmente
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal
```

Para remover: `sudo rm /usr/local/bin/ducklocal`. No Linux, crie um link do
binário extraído em `~/.local/bin`; no Windows, adicione a pasta extraída ao seu `Path`.
:::

## 3. Abra alguns dados

O primeiro início começa com um guia curto, conduzido pelo pato: trazer seu
agente de IA, abrir dados, a barra lateral, executar uma consulta e ler os resultados.
**Pular** fecha o guia em qualquer etapa. Para vê-lo de novo, escolha **Mostrar o guia** no
menu **DuckLocal** no Mac, ou no menu de clique direito da versão no
extremo direito da barra de status.

Por trás dele há uma tela intitulada **Solte seus dados aqui**. A partir dela, qualquer uma destas
ações traz dados:

- **Arraste** arquivos CSV, TSV, Parquet, JSON ou Excel — ou uma pasta inteira — para
  a janela.
- Clique em **Abrir arquivos** ou **Abrir pasta**.
- No Mac, dê **duplo clique** em um arquivo `.parquet` ou `.duckdb` no Finder, ou
  escolha DuckLocal em **Abrir com** para arquivos CSV, JSON e Excel. Veja
  [Abrir pelo Finder](data-sources.md#open-from-finder).
- Em um terminal, informe os caminhos:

  ```bash
  ducklocal ./sales.csv         # um arquivo
  ducklocal ./logs/             # todos os arquivos de dados de uma pasta, recursivamente
  ducklocal './data/*.parquet'  # um padrão — use aspas para o shell não expandir antes
  ducklocal warehouse.duckdb    # um banco de dados DuckDB existente
  ```

Cada arquivo vira uma view com o nome do arquivo — `sales.csv` vira `sales` —
e aparece em **Arquivos locais** na barra lateral com suas colunas e
contagem de linhas. O DuckLocal lê os arquivos onde eles estão; nada é copiado nem
enviado.

Os arquivos que você abre são lembrados, então o próximo início começa com o mesmo
espaço de trabalho. [Fontes de dados](data-sources.md) tem os detalhes sobre formatos,
pastas, padrões e bancos de dados.

No Mac você também pode espiar um arquivo antes de abri-lo: selecione-o no Finder
e pressione **Espaço**. A [prévia do Quick Look](data-sources.md#quick-look) do DuckLocal
mostra as colunas e as primeiras linhas de arquivos Parquet, DuckDB, CSV, TSV e JSON Lines.

::: tip Sem dados à mão?
O [tutorial dos primeiros 10 minutos](tutorial.md) percorre um arquivo de exemplo
pequeno passo a passo.
:::

## 4. Execute uma consulta

Clique em **Nova consulta** (ou abra alguns dados — o editor aparece sozinho). Digite
SQL e pressione **⌘↵** (Cmd+Enter; Ctrl+Enter no Windows e Linux):

```sql
SELECT * FROM sales LIMIT 20;
```

Substitua `sales` por qualquer nome de view da sua barra lateral.

O resultado aparece no painel abaixo do editor. Alterne para **Gráfico** para uma
imagem rápida, ou exporte como CSV ou Parquet. A barra de ferramentas acima do editor
tem **Executar**, **Formatar** e **EXPLAIN**.

Um atalho que vale a pena conhecer: na barra lateral, clique no botão de play ao lado de uma
tabela para obter um `SELECT * … LIMIT 100` pronto, ou no nome de uma coluna para selecionar
apenas aquela coluna.

## Para onde ir agora

- [Seus primeiros 10 minutos](tutorial.md) — um tour guiado com dados de exemplo
- [Fontes de dados](data-sources.md) — formatos, pastas, padrões, bancos de dados, Finder e Quick Look
- [Editor SQL](sql-editor.md) — abas, atalhos, autocompletar, EXPLAIN
- [Resultados e gráficos](results-and-charts.md) — filtragem, exportação, gráficos, a visão geral das colunas
- [Painéis (.dash)](dashboards.md) — painéis como arquivos de texto, e como revisá-los com um agente de IA
- [Solução de problemas](troubleshooting.md) — quando algo não se comporta como você espera
