# Per iniziare

> Installa DuckLocal su macOS, Windows o Linux, aggiungi la CLI ducklocal, apri un file CSV, Parquet, JSON o Excel ed esegui la tua prima query SQL in DuckDB.

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

DuckLocal è un'app desktop per fare domande con SQL ai file di dati sulla tua
macchina. Non c'è nessun server da avviare, nessuna connessione da configurare e
nessun account: indichi i file e inizi a interrogare. Questa pagina ti porta dal
download al primo risultato in circa cinque minuti.

## 1. Installa {#install}

DuckLocal funziona su macOS, Windows e Linux. I link qui sotto scaricano l'ultima versione da `dl.ducklocal.app`; gli stessi file e le note di rilascio sono su [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest).

Queste guide sono aggiornate alla [v0.4.1](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.1), pubblicata il 15 novembre 2026. La versione 0.4.0 ha aggiunto i [flussi di lavoro degli agenti](agent-workflows.md): SQL con restrizioni, un passaggio verificato alla finestra, proposte di dashboard, registri delle analisi e progetti portabili. La versione 0.4.1 aggiunge i filtri a selezione multipla, un fuso orario e un grafico timeline per le dashboard, blocchi `view` che contengono una volta sola l'SQL condiviso, estensioni della comunità come `mssql` nella scheda Estensioni, e un avviso di salvataggio per le tabelle create nel database in memoria. Se aggiorni da una versione precedente alla 0.3.0, reinstalla le estensioni: quella versione ha portato DuckLocal a DuckDB 2.0.

### Mac

Ti serve **macOS 12 o successivo su Apple silicon** (M1 o più recente).

1. Scarica [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg).
2. Aprilo e trascina **DuckLocal** su **Applicazioni**.
3. Avvia DuckLocal da Applicazioni o da Spotlight.

L'immagine disco è firmata e notarizzata da Apple, quindi si apre senza dover
aggirare Gatekeeper.

### Windows

Ti serve **Windows 10 a 64 bit o successivo**.

1. Scarica [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) ed estrailo.
2. Esegui `ducklocal.exe` dalla cartella estratta. La build non è ancora
   firmata a livello di codice, quindi al primo avvio può comparire **Windows
   ha protetto il tuo PC**: scegli **Ulteriori informazioni**, poi **Esegui
   comunque**.

### Linux

Ti serve un sistema **x86_64** con **glibc 2.35 o successivo** (Ubuntu 22.04,
Debian 12, Fedora 36 o successivo) e driver grafici con supporto 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 In alternativa, compila dai sorgenti
Ti servono Rust stabile 1.85.1 o successivo e una toolchain C++ (Xcode Command
Line Tools). DuckDB viene compilato dai sorgenti inclusi, quindi la prima
compilazione richiede diversi minuti e qualche gigabyte di disco.

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

Il binario è `./target/release/ducklocal`; usalo dove questa guida dice
`ducklocal`. Vedi [Sviluppo](development.md) per creare un bundle `.app`.
:::

## 2. Aggiungi il comando `ducklocal` (facoltativo) {#add-command}

Tutto nell'app funziona senza terminale. Se vuoi anche aprire dati dalla riga di
comando — o lasciare che un agente AI li analizzi con la [CLI](cli.md) —
aggiungi il comando dall'app:

1. Fai clic sul pulsante del robot nella barra del titolo, oppure scegli
   **DuckLocal → Riga di comando e AI…** dalla barra dei menu.
2. Fai clic su **Installa comando**. Su un Mac, il sistema chiede la tua password
   per scrivere in `/usr/local/bin`.
3. Apri un nuovo terminale e verificalo: `ducklocal --version`.

Il comando è un collegamento all'app, quindi aggiornare DuckLocal aggiorna anche
il comando. Per aggiornare, fai clic sulla versione all'estremità destra della
barra di stato: una versione più recente viene scaricata e installata al riavvio
(vedi [Controllo degli aggiornamenti](settings-and-data.md#update-check)). Va in
`/usr/local/bin` su Mac e in `~/.local/bin` su Linux; su Windows, la cartella
dell'app viene aggiunta al tuo `Path`.

Nella stessa finestra di dialogo, **Aggiungi a Claude Code** installa la skill di
DuckLocal perché Claude Code sappia interrogare i tuoi file, e **Copia il
riepilogo** copia una breve spiegazione da incollare in qualsiasi altro agente
AI. Vedi [CLI per AI e skill ufficiale](cli.md#install-the-official-skill).

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

Per rimuoverlo: `sudo rm /usr/local/bin/ducklocal`. Su Linux, collega il binario
estratto in `~/.local/bin`; su Windows, aggiungi la cartella estratta al tuo
`Path`.
:::

## 3. Apri dei dati

Il primo avvio comincia con una breve guida, condotta dalla papera: portare il
tuo agente AI, aprire i dati, la barra laterale, eseguire una query e leggere i
suoi risultati. **Salta** la chiude in qualsiasi momento. Per rivederla, scegli
**Mostra la guida** dal menu **DuckLocal** su un Mac, o dal menu contestuale
della versione all'estremità destra della barra di stato.

Dietro c'è una schermata intitolata **Trascina qui i tuoi dati**. Da qui, uno
qualsiasi di questi modi porta dati dentro:

- **Trascina** file CSV, TSV, Parquet, JSON o Excel — o un'intera cartella —
  sulla finestra.
- Fai clic su **Apri file** o **Apri cartella**.
- Su un Mac, **fai doppio clic** su un file `.parquet` o `.duckdb` nel Finder,
  oppure scegli DuckLocal in **Apri con** per i file CSV, JSON ed Excel. Vedi
  [Aprire dal Finder](data-sources.md#open-from-finder).
- Da un terminale, indica i percorsi:

  ```bash
  ducklocal ./sales.csv         # one file
  ducklocal ./logs/             # every data file under a folder, recursively
  ducklocal './data/*.parquet'  # a pattern — quote it so the shell does not expand it first
  ducklocal warehouse.duckdb    # an existing DuckDB database
  ```

Ogni file diventa una vista con il nome del file — `sales.csv` diventa `sales` —
e compare in **File locali** nella barra laterale con le sue colonne e il numero
di righe. DuckLocal legge i file dove si trovano; non viene copiato né caricato
nulla.

I file che apri vengono ricordati, quindi il prossimo avvio parte con lo stesso
spazio di lavoro. [Sorgenti di dati](data-sources.md) ha tutti i dettagli su
formati, cartelle, pattern e database.

Su un Mac puoi anche dare un'occhiata a un file prima di aprirlo: selezionalo
nel Finder e premi **Spazio**. L'[anteprima Quick Look](data-sources.md#quick-look)
di DuckLocal mostra le colonne e le prime righe dei file Parquet, DuckDB, CSV,
TSV e JSON Lines.

::: tip Non hai dati a portata di mano?
Il [tutorial dei primi 10 minuti](tutorial.md) ti guida passo passo su un
piccolo file di esempio.
:::

## 4. Esegui una query

Fai clic su **Nuova query** (o apri dei dati: l'editor compare da solo). Scrivi
SQL e premi **⌘↵** (Cmd+Invio; Ctrl+Invio su Windows e Linux):

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

Sostituisci `sales` con qualsiasi nome di vista della tua barra laterale.

Il risultato compare nel pannello sotto l'editor. Passalo a **Grafico** per
un'immagine rapida, oppure esportalo come CSV o Parquet. La barra degli strumenti
sopra l'editor ha **Esegui**, **Formatta** ed **EXPLAIN**.

Una scorciatoia che vale la pena conoscere: nella barra laterale, fai clic sul
pulsante di riproduzione accanto a una tabella per ottenere un
`SELECT * … LIMIT 100` già pronto, oppure sul nome di una colonna per
selezionare solo quella colonna.

## Dove andare adesso

- [I tuoi primi 10 minuti](tutorial.md) — un percorso guidato con dati di esempio
- [Sorgenti di dati](data-sources.md) — formati, cartelle, pattern, database, Finder e Quick Look
- [Editor SQL](sql-editor.md) — schede, scorciatoie, completamento automatico, EXPLAIN
- [Risultati e grafici](results-and-charts.md) — filtri, esportazione, grafici, la panoramica delle colonne
- [Dashboard (.dash)](dashboards.md) — dashboard come file di testo e come rivederle con un agente AI
- [Risoluzione dei problemi](troubleshooting.md) — quando qualcosa non si comporta come dovrebbe
