オプション設定

Beancountの動作は、メインの元帳ファイルの先頭に配置されるoptionディレクティブでカスタマイズします。これらのキーと値のペアは、ルート勘定科目の名前、取引が許容する不均衡の程度、実行する拡張機能を制御します。⚙️

このページのすべてのオプションはBeancount 3.2.3に対して検証されており、引用されているすべてのエラーメッセージはそのバージョンが出力するものです。Beancountは認識できないオプションを拒否します。たとえば、option "default_tolerance" "USD:0.01"はInvalid option: 'default_tolerance'で失敗します。つまり、古いガイドからコピーしたオプションは静かに失敗することはありません。ここで何かを変更した後は、必ずファイルに対してbean-checkを実行してください。

コア設定オプション​

これらのオプションは、元帳の基本的な設定を制御します。

基本設定​

これらは、設定する最も一般的なオプションの一部です。

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

• title: レポートとWebインターフェースのタイトルを設定します。デフォルトはBeancountです。
• render_commas: trueの場合、レポート内の数値は桁区切り記号（例：1,000,000.00）でフォーマットされます。デフォルトはfalseです。1、TRUE、true、yesのいずれかはtrueとして扱われます。その他の文字列はすべてfalseとして扱われます。
• plugin_processing_mode: default（デフォルト）またはrawのいずれかです。その他の値はError for option 'plugin_processing_mode'で失敗します。

rawはdefaultの緩和版ではありません。これはBeancount自身の処理段階をオフにするスイッチです。defaultでは、Beancountはプラグインの前にbeancount.ops.documentsを実行し、プラグインの後にbeancount.ops.padとbeancount.ops.balanceを実行します。rawでは、自分でリストしたプラグインのみが実行されるため、padディレクティブは適用されず、balanceアサーションはチェックされません：

; 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

その1行をdefaultに変更すると、同じファイルでBalance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little)が報告されます。rawは、意図的に自分でこれらの段階を再実装する場合にのみ使用してください。

勘定科目名のカスタマイズ​

Beancountの5つの基本勘定科目タイプの名前を変更できます。これは表面的な変更ではありません。 このオプションは、パーサーが受け入れるルート名を再定義するため、ファイル内のすべての勘定科目が新しい名前を使用する必要があり、古い名前は無効になります。

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

古いルートに1つのポスティングを残すと、ファイルはInvalid account name: Assets:Banque:Courantで読み込みを停止します。5つのオプションはname_assets、name_liabilities、name_equity、name_income、name_expensesです。各値はコロンを含まない単一の大文字の単語である必要があります。そうでない場合はError for option 'name_assets': Invalid root account nameになります。ルートの名前変更は、元帳を開始するときに行い、途中で行わないでください。

純資産勘定科目の設定​

Beancountは期間を要約する際に、期首残高、繰越利益、通貨換算など、いくつかの純資産勘定科目を合成します。これらのオプションがそれらの名前を指定します。

各値はリーフ名であり、Beancountがそれをname_equityの下に自動的に結合します。 純資産ルートを自分で記述すると、Equity:Equity:Opening-Balancesとなり、意図した勘定科目とは異なるものになります。

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はこのグループの例外です。これは完全な勘定科目名を受け取り、記述されたとおりに保存されます。そのため、上記のEquity:Roundingは正しく、プレフィックスが二重になることはありません。また、デフォルトでは未設定であり、Beancount 3.2.3では設定しても読み込みには影響しません。残余に実際に何が起こるかについては、精度と許容差を参照してください。

精度と許容差の設定​

これらのオプションは、Beancountが取引で許容する不均衡の程度を制御します。

デフォルト許容差の設定​

Beancountは、各取引の許容差をポスティングの小数位数から推測します。これらの3つのオプションは、その推測を調整します。

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

• inferred_tolerance_default: 通貨ごとの下限値。取引に推測する小数がない場合に使用されます。構文は<currency>:<number>で、*はすべての通貨を一度に設定します。オプションを繰り返して複数設定できます。
• tolerance_multiplier: 許容範囲としてカウントされる最小桁の割合。デフォルトは0.5 です。これはパーセンテージの増加ではありません。1.2にすると、すべての推測許容差がデフォルトの2.4倍になります。
• infer_tolerance_from_cost: trueの場合、原価で保有されているポスティングは、原価通貨でも許容差を広げます。デフォルトではオフです。

古い名前のinferred_tolerance_multiplierも同じ値を設定しますが、Renamed to 'tolerance_multiplier'.という読み込みエラーが報告されるため、それを使用するファイルではbean-checkが失敗します。名前を変更してください。

ブッキングメソッド​

このオプションは、減少がどのロットを引き落とすかを選択するためのデフォルトルールを設定します。特定の勘定科目には、そのopenディレクティブで異なるルールを指定できます。

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

Beancount 3.2.3は正確に7つの名前を受け入れます：STRICT（デフォルト）、STRICT_WITH_SIZE、NONE、FIFO、LIFO、HIFO、AVERAGEです。その他はすべて、読み込み時にError for option 'booking_method'で拒否されます。これには、ブッキングメソッドではない（そしてこれまで一度もなかった）SIMPLEとFULLも含まれます。AVERAGEはここで受け入れられますが、背後に実装はありません。それによる減少はAVERAGE method is not supportedを発生させます。在庫管理では、同じ元帳で7つすべてを操作します。

通貨管理​

正確なレポートには、適切な通貨設定が不可欠です。

運営通貨​

運営通貨とは、レポートで合計したい通貨です。オプションを繰り返して複数宣言できます。値は互いに置き換わるのではなく蓄積されます。

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

運営通貨を宣言すると、レポートツールはそれぞれに独自の列を提供します。conversion_currencyは、Beancountがレートゼロで換算を記帳する架空の通貨に名前を付けます。これはすでにデフォルトでNOTHINGであり、設定する理由は、元帳が実際の商品として決して使用しない別のプレースホルダーを選択することだけです。

文書管理​

Beancountは取引を領収書や請求書などの外部ファイルにリンクできます。documentsオプションは、スキャンするフォルダーを指定します。

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

そのブロック内のパスは例です。実行する前に独自のパスに置き換えてください。ルールは厳格であり、間違えた場合、それぞれがエラーではなく静かなノーオペレーションになります：

• フォルダーは存在している必要があります。 存在しない場合、読み込みはDocument root '/no/such/place' does not existで失敗します。
• サブフォルダーは勘定科目名です。 Assets:US:BofA:Checkingの明細書は<root>/Assets/US/BofA/Checking/に属します。ルートに直接置かれたファイルは無視されます。
• 勘定科目は開いている必要があります。 元帳で開かれたことのない勘定科目の下にある文書は、警告なしにスキップされます。
• ファイル名は日付で始まります。形式はYYYY-MM-DD.description.ext（例：2025-07-28.amazon-order.pdf）です。フォルダー内のその他のファイルは無視されます。
• パスは絶対パスまたはメインの元帳ファイルからの相対パスにでき、オプションは複数のフォルダーに対して繰り返すことができます。

プラグインシステム​

Beancountの機能はプラグインで拡張できます。

プラグイン設定​

プラグインは、pluginではなく、単独のoptionディレクティブで読み込まれます。 option "plugin" "..."はOption 'plugin' may not be setで失敗します。

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

そのファイルは、auto_accountsが両方の勘定科目を自動的に開くため読み込まれます。plugin行を削除すると、Invalid reference to unknown account 'Expenses:Food:Coffee'が報告されます。設定を受け取るプラグインは、2番目の文字列plugin "module" "config"として受け取ります。プラグインは、記述された順序で、Beancount自身のdocuments段階の後、padとbalance段階の前に実行されます。ただし、plugin_processing_modeをrawに設定した場合は除きます。その場合、これらの段階は完全に削除されます。

技術的な制限と制約​

これらのオプションは、Beancountパーサーの技術的な側面を制御します。

文字列処理​

複数行文字列で許可される行数に制限を設定できるため、終了引用符がない場合、ファイルの末尾ではなく、入力した場所の近くで報告されます。

option "long_string_maxlines" "64"

補間精度​

デフォルトでは、Beancountは1つの許容差を2つの異なる目的、つまり欠落した金額を埋めることと、取引のバランスが取れているかどうかを判断するために使用します。これをオンにすると、最初の目的には最も細かい推測許容差、2番目の目的には最も緩い許容差が使用され、補間された金額がずれるのを防ぎます。

option "use_precise_interpolation" "TRUE"

ポスティングに明示的な許容差を設定するオプションはありません。Beancount 3.2.3が持つ唯一の明示的な許容差構文は、balanceディレクティブのチルダ（4.271 ~ 0.01 RGAGX）であり、オプションはまったく必要ありません。取引ポスティング内のチルダは構文エラーです。

非推奨および削除されたオプション​

古いガイドがまだ推奨している3つのオプションは、Beancount 3.2.3には存在しません。このブロックの各行は読み込みに失敗します：

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

• experiment_explicit_tolerances — これが有効にしていたポスティングレベルの~構文は廃止されました。代わりにbalanceディレクティブのチルダを使用してください。
• use_legacy_fixed_tolerances — 固定された0.005/0.015許容差は廃止されました。許容差は取引ごとに推測され、tolerance_multiplierとinferred_tolerance_defaultで調整されます。
• default_tolerance — バランス調整用のinferred_tolerance_defaultとレンダリング用のdisplay_precisionに置き換えられました。

さらに3つはまだ機能しますが、非推奨エラーを報告するため、bean-checkを失敗させるのに十分です：

• inferred_tolerance_multiplier — tolerance_multiplierに名前が変更されました。
• allow_pipe_separator — 受取人と説明の間の古い|を受け入れます。
• allow_deprecated_none_for_tags_and_links — タグとリンクが属する場所にリテラルNoneを受け入れます。

Favaオプションは別物です​

このページのすべてはBeancount自身が読み取ります。Fava自身の設定はoptionディレクティブではなく、日付を持つcustom "fava-option"ディレクティブであり、Beancountはそれらを無視します。Fava設定をoptionとして記述すると、Invalid optionで失敗します。そのリストについてはFavaオプションを参照してください。

推奨設定 ✅​

ほとんどのユーザーにとって、次の設定は堅牢で合理的な出発点を提供します。これは1つのファイルであり、読み込みが成功します。

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

コメントは;で始まります。//コメントはBeancountでは構文エラーであり、ファイルの残り全体を巻き添えにします。

この設定は、新しいBeancount元帳の強固な基盤を提供し、明確なレポート、適切な精度制御、論理的な純資産勘定科目構造を保証します。