Aggiornato al 2026-09-15.
La versione 3 di Beancount, rilasciata a metà del 2024, segna un'evoluzione architetturale significativa per il popolare strumento di contabilità a testo semplice. Sebbene mantenga la compatibilità con le versioni precedenti per i file contabili degli utenti, la struttura sottostante e gli strumenti associati hanno subito modifiche sostanziali. Ecco una panoramica delle novità di Beancount v3 — e di ciò che è stato introdotto nella linea 3.1–3.2 dopo la pubblicazione di questa guida.
Per la sintassi e i primi libri contabili, consulta il riferimento alla sintassi di Beancount e Per iniziare. Per l'interfaccia a riga di comando ospitata che racchiude check, query, import e report, consulta il riferimento CLI di Beancount.
Un'Architettura Più Modulare e Semplificata
Il cambiamento più significativo in Beancount v3 è il passaggio a un ecosistema più modulare. Diverse funzionalità chiave che in precedenza erano incluse nel nucleo sono state scorporate in progetti indipendenti e separati. Questo rende il nucleo di Beancount più snello e consente uno sviluppo più mirato sui singoli componenti.
I componenti chiave che ora sono pacchetti separati includono:
- beanquery: Il potente strumento di interrogazione simile a SQL per i tuoi file contabili è ora nel suo pacchetto.
- beangulp: Questa è la nuova sede per il framework di importazione dati, che sostituisce il precedente modulo
beancount.ingest. - beanprice: Uno strumento dedicato per recuperare i prezzi di materie prime e azioni.
Questa separazione significa che gli utenti dovranno installare questi pacchetti in aggiunta a beancount stesso per mantenere tutte le funzionalità a cui erano abituati nella versione 2.
Modifiche agli Strumenti da Riga di Comando e ai Flussi di Lavoro
Riflettendo la nuova architettura modulare, ci sono alcune modifiche notevoli agli strumenti da riga di comando:
bean-reportnon è più disponibile: Questo strumento è stato rimosso. Gli utenti sono ora invitati a usarebean-query(dal pacchettobeanquery) per le loro esigenze di reportistica.- Nuovo Flusso di Lavoro per l'Importazione: I comandi
bean-extractebean-identifysono stati rimossi dal nucleo. Il nuovo approccio conbeangulpè basato su script. Gli utenti creeranno ora i propri script Python per gestire l'importazione di dati da fonti esterne come estratti conto bancari.
Miglioramenti alla Sintassi e alle Funzionalità
Sebbene i principi contabili fondamentali rimangano gli stessi, Beancount v3 introduce una gradita flessibilità nella sua sintassi:
- Codici Valuta Più Flessibili: Le restrizioni precedenti sulla lunghezza e sui caratteri per i nomi delle valute sono state allentate. Ora sono supportati simboli di valuta a carattere singolo.
- Flag di Transazione Ampliati: Gli utenti ora possono usare qualsiasi lettera maiuscola dalla A alla Z come flag per le transazioni, consentendo una categorizzazione più granulare.
È importante notare che queste modifiche sono retrocompatibili, quindi i tuoi file contabili Beancount v2 esistenti funzioneranno senza alcuna modifica.
La Riscrittura in C++ e le Prestazioni
Uno degli obiettivi a lungo termine per Beancount è stato la riscrittura dei suoi componenti critici per le prestazioni in C++. Il rilascio iniziale di Beancount v3 non includeva un nucleo in C++, e al 2026-09-15 questo resta vero: la linea PyPI pubblicata (fino alla 3.2.3) è ancora il ramo v3 modulare in Python. Il lavoro storico su C++/Bazel vive su un ramo cpp separato e non fa parte dei pacchetti che gli utenti installano da PyPI. Le prestazioni quotidiane delle attuali versioni v3 sono quindi nella stessa classe delle ultime v2, con miglioramenti incrementali al parser e agli strumenti piuttosto che una riscrittura in C++ di un ordine di grandezza.
Da Quando È Stato Scritto (v3.1 → v3.2.x)
Fonti primarie: il file CHANGES del progetto, le viste di confronto GitHub per 3.1.0…3.2.0 e PyPI beancount (ultima 3.2.3 al 2026-09-15).
- Linea 3.1.x — Continuazione della pulizia di packaging e API dopo la separazione modulare della 3.0 (
beanquery,beangulp,beanpricerimangono installazioni separate). - 3.2.0 (2025-09-14) — Commit di rilascio su
beancount/beancount; il lavoro notevole rivolto all'utente in questa finestra includebean-formatmulti-file, perfezionamenti di tolleranza/precisione e manutenzione di wheel/CI (vedi il link di confronto sopra). - 3.2.1–3.2.3 (2026) — Rilasci binari e di packaging successivi (inclusa la copertura dei test per Python 3.14 e l'impalcatura della documentazione menzionata nel riepilogo 3.2.1 sulla mailing list). Installa con
pip install -U beancounte blocca i componenti associati (beanquery,beangulp) a versioni principali corrispondenti quando aggiorni.
Fava: Fava 1.30 ha aggiunto il supporto a Beancount 3 (2024-12-29). Fava 1.30.13 (2026-05-19) ha rimosso il supporto a Beancount 2 e prevede beangulp per gli importatori. La linea PyPI attuale al 2026-09-15 è 1.30.16. Abbina gli aggiornamenti di Fava a un libro contabile Beancount 3.
Migrazione da v2 a v3
Per la maggior parte degli utenti, la migrazione da Beancount v2 a v3 è relativamente semplice:
- File Contabili: Non sono necessarie modifiche ai tuoi file
.beancount. - Installazione: Dovrai installare i nuovi pacchetti separati come
beanqueryebeangulpusandopip. - Script di Importazione: Se hai importatori personalizzati, dovrai aggiornarli per usare la nuova API
beangulp. Questo comporta principalmente il cambio della classe base da cui i tuoi importatori ereditano e l'adattamento di alcune firme di metodo. - Fava: La popolare interfaccia web per Beancount, Fava, è stata aggiornata per essere compatibile con v3. Assicurati di avere l'ultima versione di Fava per un'esperienza senza problemi.
In sostanza, Beancount v3 è un rilascio fondamentale che semplifica l'architettura del progetto, rendendolo più modulare e più facile da mantenere ed estendere nel lungo periodo. Sebbene richieda alcuni adattamenti ai flussi di lavoro degli utenti, soprattutto per quanto riguarda l'importazione di dati, getta le basi per lo sviluppo futuro di questo potente strumento contabile.
