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. Per flussi di lavoro comunitari reali che combinano plugin con importatori e Fava, consulta la vetrina della community. Le opzioni del registro che interagiscono con i plugin si trovano nella configurazione delle opzioni.

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:

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

Alcuni plugin accettano opzioni di configurazione:

; @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:

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:

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:

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:

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:

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:

; @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:

; @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:

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:

; @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:

; @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:

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 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:

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​

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

Questo set minimale fornisce automazione prevenendo errori comuni.

Per Investitori​

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​

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, includiamo il plugin auto_accounts di default in tutti i nuovi file di registro:

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 live su Beancount 3.2.3 (PyPI, 15/09/2026):

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 e nella vetrina della community — 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 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 per maggiori opzioni e la vetrina della community 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.

Pronto a provare questi plugin? Vai su Beancount.io e inizia a usarli nel tuo file di registro oggi!

Fonti​

• Riferimento API dei Plugin Beancount
• Guida a Scripting e Plugin Beancount
• Plugin e Opzioni di Beancount di Bryan Alves
• Repository GitHub di Beancount

Hai domande sui plugin di Beancount? Unisciti alla discussione sul nostro forum della community o consulta la nostra documentazione.

Esplora un registro di esempio di criptovaluta dal vivo: