# Beancount v3: Cosa c'è di nuovo?

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](/docs/Basics/syntax) e [Per iniziare](/docs/Basics/getting-started). Per l'interfaccia a riga di comando ospitata che racchiude check, query, import e report, consulta il [riferimento CLI di Beancount](/docs/bea-cli-reference).

## **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-report` non è più disponibile**: Questo strumento è stato rimosso. Gli utenti sono ora invitati a usare `bean-query` (dal pacchetto `beanquery`) per le loro esigenze di reportistica.
- **Nuovo Flusso di Lavoro per l'Importazione**: I comandi `bean-extract` e `bean-identify` sono stati rimossi dal nucleo. Il nuovo approccio con `beangulp` è 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](https://pypi.org/project/beancount/). 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](https://github.com/beancount/beancount/blob/master/CHANGES) del progetto, le viste di confronto GitHub per [3.1.0…3.2.0](https://github.com/beancount/beancount/compare/3.1.0...3.2.0) e [PyPI beancount](https://pypi.org/project/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`, `beanprice` rimangono installazioni separate).
- **3.2.0 (2025-09-14)** — Commit di rilascio su `beancount/beancount`; il lavoro notevole rivolto all'utente in questa finestra include `bean-format` multi-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 beancount` e blocca i componenti associati (`beanquery`, `beangulp`) a versioni principali corrispondenti quando aggiorni.

**Fava:** [Fava 1.30](https://beancount.github.io/fava/changelog.html) 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:

1. **File Contabili**: Non sono necessarie modifiche ai tuoi file `.beancount`.
2. **Installazione**: Dovrai installare i nuovi pacchetti separati come `beanquery` e `beangulp` usando `pip`.
3. **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.
4. **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.

## Ulteriori letture

- [Per iniziare con Beancount](/docs/Basics/getting-started)
- [Riferimento alla sintassi di Beancount](/docs/Basics/syntax)
- [Riferimento CLI di Beancount (`bea`)](/docs/bea-cli-reference)
- [Configurazioni, plugin e flussi di lavoro della community](/docs/community-showcase)
