Optionen-Konfiguration

Das Verhalten von Beancount wird mit option-Direktiven angepasst, die am Anfang Ihrer Haupt-Ledger-Datei platziert werden. Diese Schlüssel-Wert-Paare steuern die Namen Ihrer Wurzelkonten, wie viel Ungleichgewicht eine Transaktion aufweisen darf und welche Erweiterungen ausgeführt werden. ⚙️

Jede Option auf dieser Seite wurde gegen Beancount 3.2.3 geladen, und jede zitierte Fehlermeldung ist die, die diese Version ausgibt. Beancount lehnt eine nicht erkannte Option ab — option "default_tolerance" "USD:0.01" schlägt mit Invalid option: 'default_tolerance' fehl — eine Option aus einem älteren Leitfaden scheitert also nicht still. Führen Sie bea check für Ihre Datei aus, nachdem Sie hier etwas geändert haben.

Kern-Konfigurationsoptionen​

Diese Optionen steuern die grundlegende Einrichtung Ihres Ledgers.

Grundeinstellungen​

Dies sind einige der häufigsten Optionen, die Sie festlegen werden.

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

• title: Legt den Titel für Berichte und Weboberflächen fest. Standard ist Beancount.
• render_commas: Wenn wahr, werden Zahlen in Berichten mit Tausendertrennzeichen formatiert (z. B. 1,000,000.00). Standard ist falsch. Jeder der Werte 1, TRUE, true oder yes gilt als wahr; jede andere Zeichenkette als falsch.
• plugin_processing_mode: Entweder default (die Voreinstellung) oder raw. Jeder andere Wert schlägt mit Error for option 'plugin_processing_mode' fehl.

raw ist keine mildere Version von default — es ist der Schalter, der Beancounts eigene Verarbeitungsschritte deaktiviert. Unter default führt Beancount beancount.ops.documents vor Ihren Plugins und beancount.ops.pad und beancount.ops.balance danach aus. Unter raw führt es nur die Plugins aus, die Sie selbst auflisten, sodass pad-Direktiven niemals angewendet werden und balance-Prüfungen nie durchgeführt werden:

; 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

Ändern Sie diese eine Zeile auf default und dieselbe Datei meldet Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Verwenden Sie raw nur, wenn Sie diese Stufen selbst neu implementieren.

Kontonamen-Anpassung​

Sie können die fünf grundlegenden Kontotypen von Beancount umbenennen. Dies ist nicht kosmetisch. Die Option definiert neu, welche Wurzelnamen der Parser akzeptiert, sodass jedes Konto in Ihrer Datei den neuen Namen verwenden muss und der alte ungültig wird.

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

Lassen Sie eine einzelne Buchung auf der alten Wurzel und die Datei lädt nicht mehr mit Invalid account name: Assets:Banque:Courant. Die fünf Optionen sind name_assets, name_liabilities, name_equity, name_income und name_expenses; jeder Wert muss ein einzelnes großgeschriebenes Wort ohne Doppelpunkt sein, sonst erhalten Sie Error for option 'name_assets': Invalid root account name. Benennen Sie Wurzeln um, wenn Sie ein Ledger starten, nicht mitten in einem.

Eigenkapitalkonto-Konfiguration​

Beancount synthetisiert mehrere Eigenkapitalkonten, wenn es einen Zeitraum zusammenfasst — Eröffnungsbilanzen, einbehaltene Gewinne und Währungsumrechnungen. Diese Optionen benennen sie.

Jeder Wert ist ein Blattname, und Beancount fügt ihn für Sie unter name_equity ein. Wenn Sie die Eigenkapitalwurzel selbst schreiben, erhalten Sie Equity:Equity:Opening-Balances, ein anderes Konto als das beabsichtigte.

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"

account_rounding ist die Ausnahme in dieser Gruppe: Es nimmt einen vollständigen Kontonamen und wird genau so gespeichert, wie er geschrieben wird, weshalb Equity:Rounding oben korrekt ist und kein doppeltes Präfix. Es ist standardmäßig auch nicht gesetzt, und unter Beancount 3.2.3 hat das Setzen keine Auswirkung auf das Laden — siehe Präzision & Toleranzen für das, was tatsächlich mit einem Restbetrag passiert.

Präzisions- und Toleranzeinstellungen​

Diese Optionen steuern, wie viel Ungleichgewicht Beancount in einer Transaktion akzeptiert.

Standard-Toleranz-Konfiguration​

Beancount leitet eine Toleranz für jede Transaktion aus der Anzahl der Dezimalstellen in ihren Buchungen ab. Diese drei Optionen passen diese Ableitung an.

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

• inferred_tolerance_default: Eine Untergrenze pro Währung, die verwendet wird, wenn eine Transaktion keine Dezimalstellen hat, aus denen abgeleitet werden kann. Die Syntax ist <currency>:<number>, und * setzt alle Währungen auf einmal. Wiederholen Sie die Option, um mehrere zu setzen.
• tolerance_multiplier: Der Bruchteil der kleinsten Ziffer, der als tolerierbar gilt, Standard 0.5. Es ist keine prozentuale Erhöhung: 1.2 macht jede abgeleitete Toleranz 2,4-mal so groß wie die Standard-Toleranz.
• infer_tolerance_from_cost: Wenn wahr, erweitern Buchungen, die zu Anschaffungskosten gehalten werden, die Toleranz auch in der Kostenwährung. Standardmäßig aus.

Der alte Name inferred_tolerance_multiplier setzt immer noch denselben Wert, meldet aber Renamed to 'tolerance_multiplier'. als Ladefehler, sodass bea check bei einer Datei, die ihn verwendet, fehlschlägt. Benennen Sie ihn um.

Buchungsmethode​

Diese Option legt die Standardregel fest, nach der eine Reduktion welches Los abbaut. Geben Sie einem Konto eine andere Regel in seiner open-Direktive.

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

Beancount 3.2.3 akzeptiert genau sieben Namen: STRICT (die Voreinstellung), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO und AVERAGE. Alles andere wird beim Laden mit Error for option 'booking_method' abgelehnt — einschließlich SIMPLE und FULL, die keine Buchungsmethoden sind und es nie waren. AVERAGE wird hier akzeptiert, hat aber keine Implementierung dahinter; eine Reduktion unter ihm löst AVERAGE method is not supported aus. Bestandsverwaltung funktioniert über alle sieben auf demselben Ledger.

Währungsverwaltung​

Eine korrekte Währungskonfiguration ist für genaue Berichte unerlässlich.

Betriebswährung​

Eine Betriebswährung ist eine Währung, in der Berichte summiert werden sollen. Wiederholen Sie die Option, um mehr als eine zu deklarieren; die Werte akkumulieren sich, anstatt sich zu ersetzen.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Die Deklaration von Betriebswährungen teilt Berichtswerkzeugen mit, jeder Währung eine eigene Spalte zu geben. conversion_currency benennt die imaginäre Währung, in der Beancount Umrechnungen zu einem Kurs von null verbucht; sie hat bereits den Standard NOTHING, und der einzige Grund, sie zu setzen, ist, einen anderen Platzhalter zu wählen, den Ihr Ledger definitiv nie als echten Rohstoff verwendet.

Dokumentenverwaltung​

Beancount kann Transaktionen mit externen Dateien wie Belegen oder Rechnungen verknüpfen. Die documents-Option gibt ihm einen Ordner zum Durchsuchen.

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

Der Pfad in diesem Block ist eine Illustration — ersetzen Sie ihn durch Ihren eigenen, bevor Sie ihn ausführen. Die Regeln sind streng, und jede davon ist ein stiller No-op anstelle eines Fehlers, wenn Sie sie falsch machen:

• Der Ordner muss existieren. Ein fehlender Ordner führt mit Document root '/no/such/place' does not exist zum Ladefehler.
• Unterordner sind Kontonamen. Eine Erklärung für Assets:US:BofA:Checking gehört nach <root>/Assets/US/BofA/Checking/. Eine lose im Wurzelordner liegende Datei wird ignoriert.
• Das Konto muss eröffnet sein. Dokumente, die unter einem Konto gefunden werden, das Ihr Ledger nie eröffnet, werden ohne Warnung übersprungen.
• Dateinamen beginnen mit einem Datum in der Form YYYY-MM-DD.description.ext (z. B. 2025-07-28.amazon-order.pdf). Alles andere im Ordner wird ignoriert.
• Pfade können absolut oder relativ zur Haupt-Ledger-Datei sein, und die Option kann für mehrere Ordner wiederholt werden.

Plugin-System​

Die Funktionalität von Beancount kann mit Plugins erweitert werden.

Plugin-Konfiguration​

Ein Plugin wird mit einer eigenständigen plugin-Direktive geladen, nicht mit option. option "plugin" "..." schlägt mit Option 'plugin' may not be set fehl.

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

Diese Datei lädt, weil auto_accounts beide Konten für Sie eröffnet; löschen Sie die plugin-Zeile und es meldet Invalid reference to unknown account 'Expenses:Food:Coffee'. Ein Plugin, das Konfiguration akzeptiert, erhält sie als zweiten String, plugin "module" "config". Plugins laufen in der Reihenfolge, in der Sie sie schreiben, nach Beancounts eigener documents-Stufe und vor seinen pad- und balance-Stufen — es sei denn, Sie setzen plugin_processing_mode auf raw, was diese Stufen vollständig entfernt.

Technische Grenzen und Einschränkungen​

Diese Optionen steuern technische Aspekte des Beancount-Parsers.

Zeichenkettenbehandlung​

Sie können eine Grenze für die Anzahl der Zeilen festlegen, die in einer mehrzeiligen Zeichenkette erlaubt sind, sodass ein nicht abgeschlossenes Anführungszeichen in der Nähe Ihrer Eingabe gemeldet wird, anstatt am Ende der Datei.

option "long_string_maxlines" "64"

Interpolationspräzision​

Standardmäßig verwendet Beancount eine Toleranz für zwei verschiedene Aufgaben: das Auffüllen eines fehlenden Betrags und die Entscheidung, ob die Transaktion balanciert ist. Wenn Sie dies aktivieren, wird die feinste abgeleitete Toleranz für die erste und die lockerste für die zweite verwendet, was verhindert, dass interpolierte Beträge abweichen.

option "use_precise_interpolation" "TRUE"

Es gibt keine Option für explizite Toleranzen auf einer Buchung. Die einzige explizite Toleranzsyntax, die Beancount 3.2.3 hat, ist die Tilde auf einer balance-Direktive — 4.271 ~ 0.01 RGAGX — und sie benötigt überhaupt keine Option. Eine Tilde innerhalb einer Transaktionsbuchung ist ein Syntaxfehler.

Veraltete und entfernte Optionen​

Drei Optionen, die ältere Leitfäden noch empfehlen, existieren in Beancount 3.2.3 nicht mehr. Jede Zeile in diesem Block schlägt beim Laden fehl:

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

• experiment_explicit_tolerances — die Buchungsebene-~-Syntax, die es aktiviert hat, ist nicht mehr vorhanden; verwenden Sie stattdessen die Tilde einer balance-Direktive.
• use_legacy_fixed_tolerances — die festen 0.005/0.015-Toleranzen sind nicht mehr vorhanden; die Toleranz wird pro Transaktion abgeleitet, abgestimmt mit tolerance_multiplier und inferred_tolerance_default.
• default_tolerance — ersetzt durch inferred_tolerance_default für das Balancieren und display_precision für die Darstellung.

Drei weitere funktionieren noch, melden aber einen Veraltungsfehler, der ausreicht, um bea check fehlschlagen zu lassen:

• inferred_tolerance_multiplier — umbenannt in tolerance_multiplier.
• allow_pipe_separator — akzeptiert das alte | zwischen Zahlungsempfänger und Erzählung.
• allow_deprecated_none_for_tags_and_links — akzeptiert ein wörtliches None dort, wo Tags und Links hingehören.

Fava-Optionen sind getrennt​

Alles auf dieser Seite wird von Beancount selbst gelesen. Favas eigene Einstellungen sind überhaupt keine option-Direktiven — es sind custom "fava-option"-Direktiven mit einem Datum, und Beancount ignoriert sie. Eine Fava-Einstellung als option zu schreiben, schlägt mit Invalid option fehl. Siehe Fava-Optionen für diese Liste.

Empfohlene Konfiguration ✅​

Für die meisten Benutzer bietet die folgende Konfiguration einen robusten und sinnvollen Ausgangspunkt. Es ist eine Datei, und sie lädt.

; 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"

Kommentare beginnen mit ;. Ein //-Kommentar ist in Beancount ein Syntaxfehler und zieht den Rest der Datei mit in den Abgrund.

Dieses Setup bietet eine solide Grundlage für ein neues Beancount-Ledger, das klare Berichte, sinnvolle Präzisionskontrolle und eine logische Eigenkapitalkontostruktur gewährleistet.