# Plugin Natividi Essenziali di Beancount che Dovresti Conoscere

Aggiornato al 15/09/2026.

La potenza di Beancount non risiede solo nel suo formato a testo piano, ma anche nella sua estensibilità tramite i plugin. I plugin natividi sono moduli integrati che migliorano le funzionalità di Beancount, automatizzano attività noiose e impongono le migliori pratiche contabili. In questa guida completa, esploreremo tutti i plugin natividi disponibili in Beancount e come utilizzarli efficacemente.

Per la sintassi delle direttive su cui operano questi plugin, consulta il [riferimento alla sintassi di Beancount](/docs/Basics/syntax). Per flussi di lavoro comunitari reali che combinano plugin con importatori e Fava, consulta la [vetrina della community](/docs/community-showcase). Le opzioni del registro che interagiscono con i plugin si trovano nella [configurazione delle opzioni](/docs/Basics/options-configuration).



## Cosa sono i Plugin di Beancount?

I plugin di Beancount sono moduli Python che elaborano le voci del tuo registro per aggiungere funzionalità di automazione, validazione o trasformazione. Vengono eseguiti durante la fase di caricamento del file del registro e possono:

- **Automatizzare** attività ripetitive (ad es., creare dichiarazioni di conto)
- **Validare** l'integrità dei dati (ad es., controllare transazioni duplicate)
- **Trasformare** le voci (ad es., generare voci di prezzo dalle transazioni)
- **Imporre** regole contabili (ad es., una sola valuta per conto)

## Come Usare i Plugin

Per abilitare un plugin nel tuo file Beancount, aggiungi una direttiva `plugin` all'inizio del tuo registro:

```beancount
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
```

Alcuni plugin accettano opzioni di configurazione:

```beancount
; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"
```

## Categorie dei Plugin Natividi

I plugin natividi di Beancount rientrano in quattro categorie principali:

### 1. Plugin di Automazione

### 2. Plugin di Validazione

### 3. Plugin di Trasformazione

### 4. Meta-Plugin

---

## 1. Plugin di Automazione

Questi plugin automatizzano attività contabili ripetitive, facendoti risparmiare tempo e riducendo gli errori manuali.

### `auto_accounts` - Dichiarazioni di Conto Automatiche

**Cosa fa:** Inserisce automaticamente le direttive `Open` per i conti che compaiono nelle transazioni ma non sono stati dichiarati esplicitamente.

**Perché usarlo:** Elimina la necessità di dichiarare manualmente ogni conto prima di utilizzarlo. Perfetto per iniziare rapidamente o per gli utenti che preferiscono codice minimale.

**Esempio:**

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

2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD
```

Senza il plugin, dovresti aggiungere manualmente:

```beancount
2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash
```

**Quando usarlo:** Ideale per principianti o per chi desidera un registro meno verboso. Tuttavia, le dichiarazioni di conto esplicite possono aiutare a individuare errori di battitura.

---

### `close_tree` - Chiusura Automatica della Gerarchia dei Conti

**Cosa fa:** Quando chiudi un conto principale, questo plugin chiude automaticamente tutti i suoi conti discendenti.

**Perché usarlo:** Mantiene la coerenza nella gerarchia dei conti. Se chiudi `Assets:Investments`, tutti i sotto-conti come `Assets:Investments:Stocks` e `Assets:Investments:Bonds` verranno chiusi automaticamente.

**Esempio:**

```beancount
plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; These will be automatically closed:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate
```

**Quando usarlo:** Quando ristrutturi la gerarchia dei conti o chiudi intere categorie di conti.

---

### `implicit_prices` - Generazione Automatica delle Voci di Prezzo

**Cosa fa:** Sintetizza le direttive `Price` dalle registrazioni delle transazioni che includono costi (`@`) o prezzi (`@@`).

**Perché usarlo:** Popola automaticamente il database dei prezzi dalle tue transazioni, consentendo report precisi sul valore di mercato senza inserire manualmente i prezzi.

**Esempio:**

```beancount
plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD
```

Questo genera automaticamente:

```beancount
2026-01-02 price AAPL  150.00 USD
```

**Quando usarlo:** Essenziale per il monitoraggio degli investimenti e la contabilità multivalutaria dove si desidera uno storico prezzi automatico.

---

## 2. Plugin di Validazione

Questi plugin impongono l'integrità dei dati e le migliori pratiche contabili, intercettando gli errori prima che diventino problemi.

### `noduplicates` - Rilevamento Transazioni Duplicate

**Cosa fa:** Controlla che non ci siano due transazioni identiche calcolando e confrontando gli hash dei dati delle transazioni.

**Perché usarlo:** Previene inserimenti duplicati accidentali, soprattutto quando si importano transazioni da più fonti.

**Esempio:**

```beancount
; @m49-fragment expected-failure
plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; This would trigger an error:
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
```

**Quando usarlo:** Consigliato sempre, soprattutto se importi estratti conto bancari o usi più fonti di dati.

---

### `check_commodity` - Validazione delle Dichiarazioni delle Merci

**Cosa fa:** Garantisce che tutte le merci utilizzate nel tuo registro abbiano le corrispondenti direttive `Commodity`.

**Perché usarlo:** Impone dichiarazioni esplicite delle merci, aiutandoti a mantenere un elenco pulito di attività e valute.

**Esempio:**

```beancount
; @m49-fragment expected-failure
plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; This would trigger an error without a commodity declaration:
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD
```

**Quando usarlo:** Consigliato per mantenere un monitoraggio rigoroso delle merci e prevenire errori di battitura nei simboli ticker.

---

### `check_average_cost` - Validazione del Costo Medio

**Cosa fa:** Verifica che il costo medio venga preservato correttamente nelle transazioni, soprattutto quando si utilizza la contabilizzazione al costo medio.

**Perché usarlo:** Garantisce che la contabilità dei costi rimanga accurata per la dichiarazione dei redditi e il calcolo delle plusvalenze.

**Quando usarlo:** Fondamentale per i portafogli di investimento e qualsiasi scenario in cui il monitoraggio accurato dei costi sia importante.

---

### `check_closing` - Validazione della Chiusura del Saldo

**Cosa fa:** Espande i metadati di `closing` in controlli di saldo, garantendo che le posizioni siano a zero dopo le operazioni di chiusura.

**Perché usarlo:** Conferma che quando vendi un'intera posizione, il saldo sia realmente a zero (senza azioni frazionarie residue).

**Esempio:**

```beancount
plugin "beancount.plugins.check_closing"

2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.00 USD
  Income:Investments:Gains    -500.00 USD
```

Il tag `#closing` dice al plugin di verificare che la tua posizione AAPL sia a zero dopo questa transazione.

**Quando usarlo:** Quando vendi intere posizioni per assicurarti che non rimanga nulla.

---

### `coherent_cost` - Controllo di Coerenza Valuta/Costo

**Cosa fa:** Valida che le valute non vengano usate in modo incoerente — sia con che senza annotazioni di costo.

**Perché usarlo:** Previene la mescolanza di valute pure (come `100 USD`) con valute con costo (come `100 USD {1.2 CAD}`), che può causare errori contabili.

**Quando usarlo:** Consigliato per registri multivalutari per mantenere la coerenza.

---

### `leafonly` - Applicazione dei Conti Foglia

**Cosa fa:** Garantisce che solo i conti foglia (conti senza figli) ricevano registrazioni.

**Perché usarlo:** Impone una gerarchia contabile pulita dove i conti di riepilogo come `Expenses:Food` non hanno registrazioni dirette, ma solo i loro figli come `Expenses:Food:Groceries` e `Expenses:Food:Restaurants`.

**Esempio:**

```beancount
; @m49-fragment expected-failure
plugin "beancount.plugins.leafonly"

; This would trigger an error:
2026-01-02 * "Grocery shopping"
  Expenses:Food              50.00 USD  ; Error: Should post to a leaf account
  Assets:Cash               -50.00 USD

; Correct way:
2026-01-02 * "Grocery shopping"
  Expenses:Food:Groceries    50.00 USD  ; Correct: Posting to leaf account
  Assets:Cash               -50.00 USD
```

**Quando usarlo:** Quando vuoi mantenere una contabilità gerarchica rigorosa con una categorizzazione chiara.

---

### `nounused` - Rilevamento Conti Non Utilizzati

**Cosa fa:** Identifica i conti che sono stati aperti ma mai utilizzati effettivamente in alcuna transazione.

**Perché usarlo:** Ti aiuta a ripulire le dichiarazioni dei conti e a individuare potenziali errori di battitura o conti abbandonati.

**Quando usarlo:** Periodicamente, per verificare e ripulire la struttura dei tuoi conti.

---

### `onecommodity` - Una Sola Merce per Conto

**Cosa fa:** Impone che ogni conto contenga un solo tipo di merce.

**Perché usarlo:** Previene la mescolanza di attività diverse nello stesso conto, che generalmente è una buona pratica contabile.

**Esempio:**

```beancount
; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"

2026-01-02 * "Buy stocks"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD

; This would trigger an error:
2026-01-03 * "Buy more stocks"
  Assets:Investments         5 GOOGL @ 140 USD  ; Error: Different commodity
  Assets:Cash              -700.00 USD
```

**Quando usarlo:** Quando preferisci una separazione rigorosa dei conti (un conto per azione/attività).

---

### `sellgains` - Validazione delle Plusvalenze

**Cosa fa:** Controlla le plusvalenze dichiarate rispetto alle plusvalenze calcolate dalle vendite dei lotti, garantendo che i calcoli di profitto/perdita siano accurati.

**Perché usarlo:** Intercetta errori nei calcoli manuali delle plusvalenze, fondamentali per una dichiarazione dei redditi accurata.

**Esempio:**

```beancount
plugin "beancount.plugins.sellgains"

2026-01-02 * "Sell AAPL shares"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Plugin validates this is correct
```

Il plugin verificherà: Proventi della vendita (1500) - Base di costo (1400) = Plusvalenze (100)

**Quando usarlo:** Essenziale per chi fa trading di azioni, criptovalute o altri beni dove le plusvalenze contano.

---

### `unique_prices` - Controllo dell'Unicità dei Prezzi

**Cosa fa:** Garantisce che esista una sola voce di prezzo per merce per data.

**Perché usarlo:** Previene dati di prezzo contrastanti che potrebbero portare a valutazioni errate.

**Quando usarlo:** Consigliato quando si inseriscono manualmente i prezzi o si importano da più fonti di prezzi.

---

### `check_drained` - Validazione dei Conti Svuotati

**Cosa fa:** Segnala i conti che mantengono ancora un saldo (incluse valute senza prezzo o lotti residui) quando ti aspetti che siano vuoti dopo trasferimenti o chiusure.

**Perché usarlo:** Intercetta saldi residui che le verifiche del `balance` e i tag `#closing` potrebbero non rilevare — particolarmente utile dopo movimenti multivaluta.

**Stato (verificato al 15/09/2026):** Presente nell'albero Beancount 3.x su [`beancount/plugins/check_drained.py`](https://github.com/beancount/beancount/blob/master/beancount/plugins/check_drained.py) sulla linea PyPI corrente (**3.2.3**).

**Quando usarlo:** Dopo grandi riorganizzazioni del portafoglio o quando chiudi conti del broker.

---

## 3. Plugin di Trasformazione

Questi plugin modificano o migliorano i dati del tuo registro in modi utili.

### `currency_accounts` - Conti di Trading di Valute

**Cosa fa:** Implementa conti di trading di valute per tracciare esplicitamente le conversioni forex.

**Perché usarlo:** Fornisce un monitoraggio dettagliato delle transazioni di conversione valutaria, utile per gli standard contabili che lo richiedono.

**Quando usarlo:** Quando devi tracciare separatamente utili/perdite forex o soddisfare specifici requisiti contabili.

---

### `commodity_attr` - Validazione degli Attributi delle Merci

**Cosa fa:** Valida che le direttive sulle merci abbiano gli attributi richiesti (come `export`, `name`, ecc.).

**Perché usarlo:** Garantisce che i metadati delle tue merci siano completi e coerenti.

**Quando usarlo:** Quando mantieni metadati dettagliati delle merci per report o scopi di esportazione.

---

## 4. Meta-Plugin

Questi plugin sono raccolte di altri plugin per comodità.

### `auto` - Tutti i Plugin Automatici

**Cosa fa:** Abilita una raccolta di plugin "lax" o automatici in un'unica direttiva.

**Quando usarlo:** Configurazione rapida per utenti che vogliono la massima automazione con configurazione minima.

---

### `pedantic` - Tutti i Plugin di Validazione

**Cosa fa:** Abilita tutti i plugin di validazione rigorosi contemporaneamente.

**Perché usarlo:** Impone la massima integrità dei dati e rigore contabile. Ottimo per i registri di produzione o quando l'accuratezza è fondamentale.

**Esempio:**

```beancount
plugin "beancount.plugins.pedantic"

; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices
```

**Quando usarlo:** Per i registri di produzione dove vuoi la massima validazione e sei disposto a mantenere pratiche contabili più rigorose.

---

## Configurazioni Consigliate dei Plugin

### Per Principianti

```beancount
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"
```

Questo set minimale fornisce automazione prevenendo errori comuni.

### Per Investitori

```beancount
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"
```

Si concentra sul monitoraggio degli investimenti e l'accuratezza delle plusvalenze.

### Per un'Area Contabile Rigorosa

```beancount
plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"
```

Massima validazione per ambienti di produzione.

### Configurazione Predefinita su Beancount.io

Su [Beancount.io](https://beancount.io), includiamo il plugin `auto_accounts` di default in tutti i nuovi file di registro:

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

Questo fornisce un buon equilibrio tra facilità d'uso e funzionalità per iniziare rapidamente.

---

## Stato dei Plugin verificato il 15/09/2026

Contro l'albero [`beancount/plugins`](https://github.com/beancount/beancount/tree/master/beancount/plugins) live su Beancount **3.2.3** (PyPI, 15/09/2026):

| Modulo plugin | Ancora presente | Note |
| --- | --- | --- |
| `auto_accounts`, `close_tree`, `implicit_prices` | Sì | Set di automazione invariato |
| `noduplicates`, `check_commodity`, `check_average_cost`, `check_closing`, `coherent_cost`, `leafonly`, `nounused`, `onecommodity`, `sellgains`, `unique_prices` | Sì | Set di validazione invariato |
| `currency_accounts`, `commodity_attr` | Sì | Set di trasformazione invariato |
| `auto`, `pedantic` | Sì | Meta-plugin invariati |
| `check_drained` | Sì | Documentato sopra; facile da non notare nelle guide precedenti |

Nessuno di questo set nativo è stato rimosso tra la bozza originale di questa guida e la data sopra. I plugin della community (non natividi) appartengono ancora all'[elenco dei plugin di Awesome Beancount](/awesome-beancount) e nella [vetrina della community](/docs/community-showcase) — tratta i repository di terze parti come versionati indipendentemente e controlla l'ultima release di ciascun repository prima di abilitarlo su un registro di produzione.

---

## Migliori Pratiche

1. **Inizia in modo minimale, aggiungi quando serve:** Inizia con `auto_accounts` e `noduplicates`, poi aggiungi i plugin di validazione man mano che il tuo registro matura.

2. **Testa i plugin singolarmente:** Quando aggiungi più plugin, abilitali uno alla volta per capirne gli effetti.

3. **Leggi attentamente i messaggi di errore:** Gli errori dei plugin spesso indicano problemi contabili reali che richiedono una correzione.

4. **Usa `pedantic` per la produzione:** Una volta stabilito il tuo flusso di lavoro, considera l'abilitazione della validazione rigorosa.

5. **Combina con plugin personalizzati:** I plugin natividi funzionano insieme a plugin personalizzati come il [plugin forecast](https://beancount.io/blog/2022/05/30/forecast-plugin) per la massima funzionalità.

---

## Oltre i Plugin Natividi

Mentre i plugin natividi forniscono funzionalità di base, l'ecosistema Beancount include molti plugin sviluppati dalla community per esigenze specializzate:

- **fava.plugins.forecast** - Per la previsione di transazioni ricorrenti
- **fava.plugins.link_documents** - Per collegare transazioni a file di ricevute
- Importatori personalizzati per formati CSV specifici della banca
- Calcolatori e report specifici per le tasse

Esplora l'[ecosistema Beancount](https://beancount.io/awesome-beancount) per maggiori opzioni e la [vetrina della community](/docs/community-showcase) per vedere come le persone combinano plugin natividi con importatori e Fava.

---

## Conclusione

I plugin natividi di Beancount trasformano la contabilità a testo piano da un processo manuale a un sistema di gestione finanziaria automatizzato, validato e robusto. Comprendendo e sfruttando questi strumenti integrati, puoi:

- ✅ Automatizzare attività contabili noiose
- ✅ Intercettare errori prima che diventino problemi
- ✅ Mantenere una rigorosa integrità dei dati
- ✅ Generare report finanziari accurati
- ✅ Concentrarti sugli insight finanziari piuttosto che sull'inserimento dati

Inizia a sperimentare con questi plugin nel tuo registro oggi. Inizia con `auto_accounts` e `implicit_prices`, poi aggiungi gradualmente i plugin di validazione man mano che le tue pratiche contabili maturano.

---

## Fonti

- [Riferimento API dei Plugin Beancount](https://beancount.github.io/docs/api_reference/beancount.plugins.html)
- [Guida a Scripting e Plugin Beancount](https://beancount.github.io/docs/beancount_scripting_plugins.html)
- [Plugin e Opzioni di Beancount di Bryan Alves](https://bryanalves.github.io/posts/2022-09-01-beancount-plugins-and-options/)
- [Repository GitHub di Beancount](https://github.com/beancount/beancount)

---

_Hai domande sui plugin di Beancount? Unisciti alla discussione sul nostro [forum della community](https://beancount.io/forum) o consulta la nostra [documentazione](https://beancount.io/docs/help-center)._

Esplora un registro di esempio di criptovaluta dal vivo:

<LedgerEmbed
  username="open_ledger"
  ledger="crypto-example"
  page=""
  title="Registro di Esempio di Criptovaluta"
/>
