知っておくべき主要な Beancount ネイティブプラグイン

2026年1月2日 · 約14分

Mike Thrift

Marketing Manager

Beancountの強力さは、単にプレーンテキスト形式であることだけでなく、プラグインによる拡張性にもあります。ネイティブプラグインは、Beancountの機能を強化し、退屈な作業を自動化し、会計のベストプラクティスを強制するための組み込みモジュールです。この包括的なガイドでは、Beancountで利用可能なすべてのネイティブプラグインとその効果的な使用方法について解説します。

Beancountプラグインとは何ですか？

Beancountプラグインは、帳簿（ledger）エントリを処理して、自動化、検証、または変換機能を追加するPythonモジュールです。これらは帳簿ファイルのロードフェーズ中に実行され、以下のことが可能です：

繰り返しの作業を自動化する（例：勘定科目の宣言の作成）
データの整合性を検証する（例：重複トランザクションのチェック）
エントリを変換する（例：トランザクションから価格エントリを生成する）
会計ルールを強制する（例：1つの勘定科目につき1つのコモディティ）

プラグインの使用方法

Beancountファイルでプラグインを有効にするには、帳簿の冒頭に plugin ディレクティブを追加します：

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

一部のプラグインは設定オプションを受け入れます：

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

ネイティブプラグインのカテゴリ

Beancountのネイティブプラグインは、主に次の4つのカテゴリに分類されます：

1. 自動化プラグイン

2. 検証プラグイン

3. 変換プラグイン

4. メタプラグイン

1. 自動化プラグイン

これらのプラグインは繰り返しの記帳作業を自動化し、時間を節約し、手動によるミスを減らします。

`auto_accounts` - 勘定科目の自動宣言

機能: トランザクションに登場するが明示的に宣言されていない勘定科目に対して、自動的に Open ディレクティブを挿入します。

使用する理由: すべての勘定科目を使用前に手動で宣言する手間を省きます。手早く始めたい場合や、定型的な記述を最小限に抑えたいユーザーに最適です。

例:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

このプラグインがない場合、以下を手動で追加する必要があります：

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

使用時期: 初心者や、冗長でない帳簿を好む人に適しています。ただし、明示的な勘定科目の宣言は、入力ミス（タイポ）を見つけるのに役立ちます。

`close_tree` - 勘定科目階層の自動クローズ

機能: 親の勘定科目をクローズすると、このプラグインはそのすべての子孫勘定科目も自動的にクローズします。

使用する理由: 勘定科目階層の一貫性を維持します。Assets:Investments をクローズすると、Assets:Investments:Stocks や Assets:Investments:Bonds などのサブアカウントもすべて自動的にクローズされます。

例:

plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; 以下は自動的にクローズされます：
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

使用時期: 勘定科目階層を再構成する場合や、カテゴリ全体をクローズする場合に使用します。

`implicit_prices` - 価格エントリの自動生成

機能: コスト（@）または価格（@@）を含むトランザクションのポスティングから Price ディレクティブを合成します。

使用する理由: トランザクションから自動的に価格データベースを構築し、手動で価格を入力することなく、正確な時価評価レポートを可能にします。

例:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

これにより、以下が自動的に生成されます：

2026-01-02 price AAPL  150.00 USD

使用時期: 投資の追跡や、自動的な価格履歴が必要な多通貨会計には不可欠です。

2. 検証プラグイン

これらのプラグインはデータの整合性と会計のベストプラクティスを強制し、問題が発生する前にエラーをキャッチします。

`noduplicates` - 重複トランザクションの検出

機能: トランザクションデータのハッシュ値を計算して比較することで、2つのトランザクションが同一でないかチェックします。

使用する理由: 特に複数のソースからトランザクションをインポートする場合に、誤った重複エントリを防ぎます。

例:

plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; これはエラーを引き起こします：
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

使用時期: 常に推奨されます。特に銀行の明細書からインポートしたり、複数のデータソースを使用したりする場合に有効です。

`check_commodity` - コモディティ宣言の検証

機能: 帳簿で使用されるすべてのコモディティに、対応する Commodity ディレクティブがあることを確認します。

使用する理由: 明示的なコモディティ宣言を強制し、資産や通貨のクリーンなリストを維持するのに役立ちます。

例:

plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; コモディティ宣言がない場合、これはエラーを引き起こします：
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

使用時期: 厳密なコモディティ追跡を維持し、ティッカーシンボルの入力ミスを防ぐために推奨されます。

`check_average_cost` - コストベースの検証

機能: トランザクション、特に平均法（average-cost booking）を使用している場合に、コストベースが正しく保持されているかを検証します。

使用する理由: 税務報告やキャピタルゲインの計算において、コスト会計の正確性を維持するために重要です。

使用するタイミング: 投資ポートフォリオや、正確なコスト追跡が重要となるあらゆるシナリオにおいて不可欠です。

`check_closing` - 決済時の残高検証

機能: closing メタデータを残高チェックに拡張し、ポジションをクローズする取引の後に残高がゼロになっていることを確認します。

使用する理由: ポジションを全売却した際に、残高が本当にゼロであること（端株などが残っていないこと）を確認できます。

例:

plugin "beancount.plugins.check_closing"

2026-01-02 * "AAPLの全ポジションを決済" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15000.00 USD
  Income:Investments:Gains   -500.00 USD

#closing タグは、このトランザクションの後に AAPL のポジションがゼロであることを検証するようプラグインに指示します。

使用するタイミング: ポジションを全売却し、何も残っていないことを確実にしたい場合に使用します。

`coherent_cost` - 通貨とコストの一貫性チェック

機能: 通貨が不自然な形で（コスト注釈がある場合とない場合が混在するなど）使用されていないかを検証します。

使用する理由: 単なる通貨（例: 100 USD）とコスト指定のある通貨（例: 100 USD {1.2 CAD}）の混在を防ぎます。これらが混ざると会計エラーの原因となります。

使用するタイミング: 一貫性を維持するために、多通貨の帳簿で推奨されます。

`leafonly` - リーフアカウントへの記帳制限

機能: リーフアカウント（子アカウントを持たない末端の勘定）に対してのみ記帳が行われるように制限します。

使用する理由: Expenses:Food のような集計用のアカウントに直接記帳せず、その子アカウントである Expenses:Food:Groceries や Expenses:Food:Restaurants にのみ記帳させることで、クリーンな勘定体系を維持します。

例:

plugin "beancount.plugins.leafonly"

; これはエラーになります:
2026-01-02 * "食料品の買い物"
  Expenses:Food              50.00 USD  ; エラー: リーフアカウントに記帳する必要があります
  Assets:Cash               -50.00 USD

; 正しい方法:
2026-01-02 * "食料品の買い物"
  Expenses:Food:Groceries    50.00 USD  ; 正解: リーフアカウントへの記帳
  Assets:Cash               -50.00 USD

使用するタイミング: 明確な分類を伴う厳格な階層型会計を維持したい場合に使用します。

`nounused` - 未使用アカウントの検出

機能: 開設されたものの、一度もトランザクションで使用されていないアカウントを特定します。

使用する理由: 勘定科目の宣言を整理し、入力ミスや放棄されたアカウントを見つけるのに役立ちます。

使用するタイミング: 定期的に、勘定体系を監査およびクリーンアップするために使用します。

`onecommodity` - 1勘定1コモディティの制限

機能: 各アカウントが1種類のコモディティ（通貨や商品）のみを保持するように制限します。

使用する理由: 同一のアカウント内で異なる資産が混ざることを防ぎます。これは一般的に会計上のベストプラクティスとされています。

例:

plugin "beancount.plugins.onecommodity"

2026-01-02 * "株を購入"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD

; これはエラーになります:
2026-01-03 * "さらに株を購入"
  Assets:Investments         5 GOOGL @ 140 USD  ; エラー: 異なるコモディティ
  Assets:Cash              -700.00 USD

使用するタイミング: 厳格な勘定分離（1銘柄/1資産につき1勘定）を好む場合に使用します。

`sellgains` - キャピタルゲイン（譲渡益）の検証

機能: 申告されたキャピタルゲインと、ロット売却から算出された利益を照合し、損益計算が正確であることを確認します。

使用する理由: 手動によるキャピタルゲイン計算の誤りを防ぎます。正確な税務報告に不可欠です。

例:

plugin "beancount.plugins.sellgains"

2026-01-02 * "AAPL株を売却"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; プラグインがこれが正しいことを検証します

プラグインは「売却額 (1500) - 取得原価 (1400) = 利益 (100)」であることを確認します。

使用するタイミング: 株式、暗号資産、その他キャピタルゲインが発生する資産を取引するすべての人に必須です。

`unique_prices` - 価格の一意性チェック

機能: 特定の日付において、1つのコモディティに対して1つの価格エントリのみが存在することを保証します。

使用する理由: 評価額の誤りにつながる可能性のある、競合する価格データの混入を防ぎます。

使用するタイミング: 価格を手動で入力する場合や、複数の価格ソースからインポートする場合に推奨されます。

3. 変換プラグイン (Transformation Plugins)

これらのプラグインは、帳簿データを便利な方法で修正または強化します。

`currency_accounts` - 通貨取引勘定

機能: 外貨両替を明示的に追跡するための通貨取引勘定を実装します。

使用する理由: 通貨換算取引の詳細な追跡を可能にします。これを必要とする会計基準に対応する際に役立ちます。

使用するタイミング: 為替差損益を個別に追跡する必要がある場合や、特定の会計要件を満たす必要がある場合に使用します。

`commodity_attr` - コモディティ属性の検証

機能: commodity ディレクティブに、必要な属性（export、name など）が含まれているかを検証します。

使用する理由: コモディティのメタデータが完全で一貫していることを保証します。

使用するタイミング: レポート作成やエクスポートのために、詳細なコモディティメタデータを管理している場合に使用します。

4. メタプラグイン

これらのプラグインは、利便性のために他のプラグインをまとめたコレクションです。

`auto` - すべての自動化プラグイン

機能： 1つのディレクティブで、一連の「寛容な」あるいは自動化プラグインを有効にします。

使用場面： 最小限の設定で最大限の自動化を求めるユーザー向けのクイックセットアップ。

`pedantic` - すべての検証プラグイン

機能： すべての厳格な検証プラグインを一度に有効にします。

使用理由： データの整合性と会計上の厳密さを最大限に高めます。本番用元帳や、正確性が極めて重要な場合に適しています。

例：

plugin "beancount.plugins.pedantic"

; これは以下を有効にするのと同等です：
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

使用場面： 最大限の検証を必要とし、より厳格な会計慣行を維持する意思がある本番用元帳。

推奨されるプラグイン構成

初心者向け

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

この最小限のセットは、一般的なエラーを防ぎながら自動化を実現します。

投資家向け

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"

投資の追跡とキャピタルゲインの正確性に焦点を当てています。

厳格な会計向け

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

本番環境向けの最大限の検証。

Beancount.io でのデフォルト構成

Beancount.io では、すべての新しい元帳ファイルにデフォルトで auto_accounts プラグインを含めています。

plugin "beancount.plugins.auto_accounts"

これにより、すぐに使い始めるための使いやすさと機能性の優れたバランスが提供されます。

ベストプラクティス

最小限から始め、必要に応じて追加する： まずは auto_accounts と noduplicates から始め、元帳が成熟するにつれて検証プラグインを追加します。
プラグインを個別にテストする： 複数のプラグインを追加する場合は、その効果を理解するために1つずつ有効にしてください。
エラーメッセージを注意深く読む： プラグインのエラーは多くの場合、修正が必要な実際の会計上の問題を指し示しています。
本番用には pedantic を使用する： ワークフローが確立したら、厳格な検証を有効にすることを検討してください。
カスタムプラグインと組み合わせる： ネイティブプラグインは、機能を最大限に引き出すために、予測プラグイン（forecast plugin）のようなカスタムプラグインと併用できます。

ネイティブプラグインの先へ

ネイティブプラグインはコア機能を提供しますが、Beancount のエコシステムには、特定のニーズに対応するためのコミュニティ開発のプラグインが数多く含まれています。

fava.plugins.forecast - 繰り返される取引の予測用
fava.plugins.link_documents - 取引を領収書ファイルにリンクするため
銀行固有の CSV 形式用のカスタムインポーター
税金固有の計算機やレポート

その他のオプションについては、Beancount エコシステムを探索してください。

結論

Beancount のネイティブプラグインは、プレーンテキスト会計を手動のプロセスから、自動化され、検証された堅牢な財務管理システムへと変貌させます。これらの組み込みツールを理解し活用することで、以下のことが可能になります。

✅ 退屈な帳簿付け作業を自動化する
✅ 問題になる前にエラーを察知する
✅ 厳格なデータの整合性を維持する
✅ 正確な財務レポートを作成する
✅ データ入力ではなく、財務上の洞察に集中する

今日から元帳でこれらのプラグインを試してみてください。まずは auto_accounts と implicit_prices から始め、会計慣行が成熟するにつれて徐々に検証プラグインを追加していきましょう。

これらのプラグインを試す準備はできましたか？ Beancount.io にアクセスして、今すぐ元帳ファイルで使用を開始しましょう！

出典

Beancount プラグインについて質問がありますか？コミュニティフォーラムでの議論に参加するか、ヘルプセンターのドキュメントを確認してください。

References:

Share on Twitter Follow @beancount_io

Beancountプラグインとは何ですか？​

プラグインの使用方法​

ネイティブプラグインのカテゴリ​

1. 自動化プラグイン​

2. 検証プラグイン​

3. 変換プラグイン​

4. メタプラグイン​

1. 自動化プラグイン​

auto_accounts - 勘定科目の自動宣言​

close_tree - 勘定科目階層の自動クローズ​

implicit_prices - 価格エントリの自動生成​

2. 検証プラグイン​

noduplicates - 重複トランザクションの検出​

check_commodity - コモディティ宣言の検証​

check_average_cost - コストベースの検証​

check_closing - 決済時の残高検証​

coherent_cost - 通貨とコストの一貫性チェック​

leafonly - リーフアカウントへの記帳制限​

nounused - 未使用アカウントの検出​

onecommodity - 1勘定1コモディティの制限​

sellgains - キャピタルゲイン（譲渡益）の検証​

unique_prices - 価格の一意性チェック​

3. 変換プラグイン (Transformation Plugins)​

currency_accounts - 通貨取引勘定​

commodity_attr - コモディティ属性の検証​

4. メタプラグイン​

auto - すべての自動化プラグイン​

pedantic - すべての検証プラグイン​

推奨されるプラグイン構成​

初心者向け​

投資家向け​

厳格な会計向け​

Beancount.io でのデフォルト構成​

ベストプラクティス​

ネイティブプラグインの先へ​

結論​

出典​

Beancount.ioを始める

はじめに

機能

コミュニティ

法務

Beancountプラグインとは何ですか？

プラグインの使用方法

ネイティブプラグインのカテゴリ

1. 自動化プラグイン

2. 検証プラグイン

3. 変換プラグイン

4. メタプラグイン

1. 自動化プラグイン

`auto_accounts` - 勘定科目の自動宣言

`close_tree` - 勘定科目階層の自動クローズ

`implicit_prices` - 価格エントリの自動生成

2. 検証プラグイン

`noduplicates` - 重複トランザクションの検出

`check_commodity` - コモディティ宣言の検証

`check_average_cost` - コストベースの検証

`check_closing` - 決済時の残高検証

`coherent_cost` - 通貨とコストの一貫性チェック

`leafonly` - リーフアカウントへの記帳制限

`nounused` - 未使用アカウントの検出

`onecommodity` - 1勘定1コモディティの制限

`sellgains` - キャピタルゲイン（譲渡益）の検証

`unique_prices` - 価格の一意性チェック

3. 変換プラグイン (Transformation Plugins)

`currency_accounts` - 通貨取引勘定

`commodity_attr` - コモディティ属性の検証

4. メタプラグイン

`auto` - すべての自動化プラグイン

`pedantic` - すべての検証プラグイン

推奨されるプラグイン構成

初心者向け

投資家向け

厳格な会計向け

Beancount.io でのデフォルト構成

ベストプラクティス

ネイティブプラグインの先へ

結論

出典