# Configurare i ledger Beancount con le direttive option

Il comportamento di Beancount viene personalizzato con direttive `option` poste all'inizio di [il tuo file di registro principale](https://beancount.io/it/docs/Tips/multi-file-support). Queste coppie chiave-valore controllano i nomi dei tuoi conti radice, quanto sbilanciamento una transazione può contenere e quali estensioni vengono eseguite. ⚙️

Ogni opzione in questa pagina è stata caricata con **Beancount 3.2.3**, e ogni messaggio di errore citato è quello stampato da questa versione. Beancount rifiuta un'opzione che non riconosce — `option "default_tolerance" "USD:0.01"` fallisce con `Invalid option: 'default_tolerance'` — quindi un'opzione copiata da una guida più vecchia non fallisce in silenzio. Esegui `bea check` sul tuo file dopo aver modificato qualsiasi cosa qui.

## Opzioni di Configurazione Principali

Queste opzioni controllano l'impostazione fondamentale del tuo registro.

### Impostazioni di Base

Queste sono alcune delle opzioni più comuni che imposterai.

```bean
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"
```

- **`title`**: Imposta il titolo per report e interfacce web. Il valore predefinito è `Beancount`.
- **`render_commas`**: Se true, i numeri nei report sono formattati con separatori delle migliaia (es., `1,000,000.00`). Il valore predefinito è false. Qualsiasi valore tra `1`, `TRUE`, `true` o `yes` viene letto come true; qualsiasi altra stringa viene letta come false.
- **`plugin_processing_mode`**: O `default` (il valore predefinito) oppure `raw`. Qualsiasi altro valore fallisce con `Error for option 'plugin_processing_mode'`.

`raw` non è una versione più leggera di `default` — è l'interruttore che disattiva le fasi di elaborazione di Beancount stesso. Con `default`, Beancount esegue `beancount.ops.documents` prima dei tuoi plugin e `beancount.ops.pad` e `beancount.ops.balance` dopo di essi. Con `raw` esegue solo i plugin che elenchi tu stesso, quindi le direttive `pad` non vengono mai applicate e **le verifiche `balance` non vengono mai eseguite**:

```bean
; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"

1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances

1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD

1970-01-03 balance Assets:Cash   999.00 USD
```

Cambia quella riga in `default` e lo stesso file riporta `Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little)`. Usa `raw` solo quando stai deliberatamente reimplementando quelle fasi da solo.

### Personalizzazione dei Nomi dei Conti

Puoi rinominare i [cinque tipi di conto fondamentali](/blog/2026/04/08/debits-and-credits-explained-a-plain-english-guide-for-small-business-owners) di Beancount. **Questa non è un'operazione estetica.** L'opzione ridefinisce quali nomi radice il parser accetta, quindi ogni conto nel tuo file deve usare il nuovo nome e il vecchio diventa non valido.

```bean
option "name_assets" "Actifs"
option "name_expenses" "Depenses"

2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation

2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR
```

Lascia una singola registrazione sulla vecchia radice e il file smette di caricarsi con `Invalid account name: Assets:Banque:Courant`. Le cinque opzioni sono `name_assets`, `name_liabilities`, `name_equity`, `name_income` e `name_expenses`; ogni valore deve essere una singola parola con la maiuscola senza due punti, altrimenti ottieni `Error for option 'name_assets': Invalid root account name`. Rinomina le radici quando inizi un registro, non a metà.

### Configurazione dei Conti di Patrimonio Netto

Beancount sintetizza diversi conti di patrimonio netto quando riepiloga un periodo — saldi di apertura, utili portati a nuovo e conversioni di valuta. Queste opzioni li nominano.

**Ogni valore è un nome di foglia e Beancount lo unisce sotto `name_equity` per te.** Scrivere la radice del patrimonio netto da soli produce `Equity:Equity:Opening-Balances`, che è un conto diverso da quello che intendevi.

```bean
option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"
```

| Opzione | Foglia predefinita | Conto risultante |
| --- | --- | --- |
| `account_previous_balances` | `Opening-Balances` | `Equity:Opening-Balances` |
| `account_previous_earnings` | `Earnings:Previous` | `Equity:Earnings:Previous` |
| `account_current_earnings` | `Earnings:Current` | `Equity:Earnings:Current` |
| `account_previous_conversions` | `Conversions:Previous` | `Equity:Conversions:Previous` |
| `account_current_conversions` | `Conversions:Current` | `Equity:Conversions:Current` |

`account_rounding` è l'eccezione in questo gruppo: accetta un **nome completo** del conto e viene memorizzato esattamente come scritto, motivo per cui `Equity:Rounding` sopra è corretto e non un prefisso raddoppiato. Inoltre, non è impostato per impostazione predefinita e su Beancount 3.2.3 impostarlo non ha alcun effetto sul caricamento — consulta [Precisione e Tolleranze](https://beancount.io/it/docs/Basics/precision) per ciò che accade realmente a un residuo.

## Impostazioni di Precisione e Tolleranza

Queste opzioni controllano quanto sbilanciamento Beancount accetta in una transazione.

### Configurazione della Tolleranza Predefinita

Beancount [deduce una tolleranza](https://beancount.io/it/docs/Basics/precision) per ogni transazione dal numero di cifre decimali nelle sue registrazioni. Queste tre opzioni regolano quella deduzione.

```bean
option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"
```

- **`inferred_tolerance_default`**: Un livello minimo per valuta, usato quando una transazione non ha decimali da cui dedurre. La sintassi è `<currency>:<number>` e `*` imposta tutte le valute contemporaneamente. Ripeti l'opzione per impostarne diverse.
- **`tolerance_multiplier`**: La frazione della cifra più piccola che conta come tollerabile, **predefinito `0.5`**. Non è un aumento percentuale: `1.2` rende ogni tolleranza dedotta 2.4 volte quella predefinita.
- **`infer_tolerance_from_cost`**: Se true, le registrazioni mantenute al costo ampliano la tolleranza anche nella valuta di costo. Disattivata per impostazione predefinita.

Il vecchio nome `inferred_tolerance_multiplier` imposta ancora lo stesso valore, ma riporta `Renamed to 'tolerance_multiplier'.` come errore di caricamento, quindi `bea check` fallisce su un file che lo usa. Rinominalo.

### Metodo di Prenotazione

Questa opzione imposta la regola predefinita per scegliere quale lotto viene prelevato da una riduzione. Dai a un conto una regola diversa sulla sua direttiva `open`.

```bean
; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"
```

Beancount 3.2.3 accetta esattamente sette nomi: `STRICT` (il predefinito), `STRICT_WITH_SIZE`, `NONE`, `FIFO`, `LIFO`, `HIFO` e `AVERAGE`. Qualsiasi altro valore viene rifiutato al caricamento con `Error for option 'booking_method'` — incluso `SIMPLE` e `FULL`, che non sono metodi di prenotazione e non lo sono mai stati. `AVERAGE` è accettato qui ma non ha alcuna implementazione dietro; una riduzione sotto di esso solleva `AVERAGE method is not supported`. [Gestione dell'Inventario](https://beancount.io/it/docs/Basics/inventories) funziona con tutti e sette sullo stesso registro.

## Gestione delle Valute

Una corretta configurazione delle valute è fondamentale per una reportistica accurata.

### Valuta Operativa

Una valuta operativa è una valuta in cui desideri che i report totalizzino. Ripeti l'opzione per dichiararne più di una; i valori si accumulano piuttosto che sostituirsi a vicenda.

```bean
option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"
```

La dichiarazione delle valute operative dice agli strumenti di reportistica di dare a ciascuna la propria colonna. `conversion_currency` nomina la valuta immaginaria in cui Beancount registra le conversioni a un tasso di zero; è già predefinita a `NOTHING`, e l'unico motivo per impostarla è scegliere un segnaposto diverso che il tuo registro sicuramente non usa mai come merce reale.

## Gestione dei Documenti

Beancount può collegare le transazioni a file esterni come ricevute o fatture. L'opzione `documents` gli fornisce una cartella da scansionare.

```bean
option "documents" "/home/user/Documents/beancount"
```

Il percorso in quel blocco è un'illustrazione — sostituisci il tuo prima di eseguirlo. Le regole sono rigide e ciascuna di esse è una non-operazione silenziosa piuttosto che un errore quando sbagli:

- **La cartella deve esistere.** Una cartella mancante fa fallire il caricamento con `Document root '/no/such/place' does not exist`.
- **Le sottocartelle sono nomi di conto.** Un estratto conto per `Assets:US:BofA:Checking` appartiene a `<root>/Assets/US/BofA/Checking/`. Un file che giace libero nella radice viene ignorato.
- **Il conto deve essere aperto.** I documenti trovati sotto un conto che il tuo registro non apre mai vengono saltati senza un avviso.
- **I nomi dei file iniziano con una data**, nella forma `YYYY-MM-DD.description.ext` (es., `2025-07-28.amazon-order.pdf`). Qualsiasi altra cosa nella cartella viene ignorata.
- I percorsi possono essere assoluti o relativi al file di registro principale e l'opzione può essere ripetuta per diverse cartelle.

## Sistema di Plugin

Le funzionalità di Beancount possono essere estese con plugin.

### Configurazione dei Plugin

**Un plugin viene caricato con una direttiva `plugin` autonoma, non con `option`.** `option "plugin" "..."` fallisce con `Option 'plugin' may not be set`.

```bean
plugin "beancount.plugins.auto_accounts"

2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD
```

Quel file si carica perché `auto_accounts` apre entrambi i conti per te; elimina la riga `plugin` e riporta `Invalid reference to unknown account 'Expenses:Food:Coffee'`. Un plugin che accetta configurazione la riceve come seconda stringa, `plugin "module" "config"`. I plugin vengono eseguiti nell'ordine in cui li scrivi, dopo la fase `documents` di Beancount e prima delle sue fasi `pad` e `balance` — a meno che tu non imposti `plugin_processing_mode` su `raw`, che elimina del tutto queste fasi.

## Limiti Tecnici e Vincoli

Queste opzioni controllano aspetti tecnici del parser di Beancount.

### Gestione delle Stringhe

Puoi impostare un limite al numero di righe consentite in una stringa multilinea, così una virgoletta non terminata viene riportata vicino a dove l'hai digitata piuttosto che alla fine del file.

```bean
option "long_string_maxlines" "64"
```

### Precisione dell'Interpolazione

Per impostazione predefinita Beancount usa una tolleranza per due compiti diversi: riempire un importo mancante e decidere se la transazione è bilanciata. Attivare questa opzione usa la tolleranza dedotta più fine per il primo e quella più lasca per il secondo, il che impedisce agli importi interpolati di deviare.

```bean
option "use_precise_interpolation" "TRUE"
```

Non esiste alcuna opzione per tolleranze esplicite su una registrazione. L'unica sintassi di tolleranza esplicita che Beancount 3.2.3 ha è la tilde su una direttiva `balance` — `4.271 ~ 0.01 RGAGX` — e non richiede alcuna opzione. Una tilde all'interno di una registrazione di transazione è un errore di sintassi.

## Opzioni Deprecate e Rimosse

Tre opzioni che guide più vecchie raccomandano ancora non esistono in Beancount 3.2.3. Ogni riga in questo blocco fa fallire il caricamento:

```bean
option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"
```

- `experiment_explicit_tolerances` — la sintassi `~` a livello di registrazione che abilitava è sparita; usa invece la tilde di una direttiva `balance`.
- `use_legacy_fixed_tolerances` — le tolleranze fisse `0.005`/`0.015` sono sparite; la tolleranza viene dedotta per transazione, regolata con `tolerance_multiplier` e `inferred_tolerance_default`.
- `default_tolerance` — sostituita da `inferred_tolerance_default` per il bilanciamento e `display_precision` per la resa.

Altri tre funzionano ancora ma riportano un errore di deprecazione, che è sufficiente per far fallire `bea check`:

- `inferred_tolerance_multiplier` — rinominata a `tolerance_multiplier`.
- `allow_pipe_separator` — accetta la vecchia `|` tra beneficiario e narrazione.
- `allow_deprecated_none_for_tags_and_links` — accetta un letterale `None` dove appartengono tag e link.

## Le opzioni di Fava sono separate

Tutto su questa pagina viene letto da Beancount stesso. Le impostazioni di Fava non sono affatto direttive `option` — sono direttive `custom "fava-option"` con una data e Beancount le ignora. Scrivere un'impostazione di Fava come `option` fallisce con `Invalid option`. Consulta [Opzioni di Fava](https://beancount.io/it/docs/Basics/fava-options) per quell'elenco.

## Configurazione Raccomandata ✅

Per la maggior parte degli utenti, la seguente configurazione fornisce un punto di partenza robusto e sensato. È un unico file e si carica.

```bean
; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"

; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"

; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"

; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"
```

I commenti iniziano con `;`. Un commento `//` è un errore di sintassi in Beancount e trascina con sé il resto del file.

Questa configurazione fornisce una solida base per un [nuovo registro Beancount](https://beancount.io/it/docs/Basics/getting-started), garantendo una reportistica chiara, un controllo sensato della precisione e una struttura logica dei conti di patrimonio netto.
