Beancountのコア機能と哲学
Beancountは、プレーンテキストファイルを使用して取引を記録する、オープンソースの複式簿記会計システムです。その核心において、Beancountはあなたの台帳を、シンプルで厳格な文法によ って定義された_データセット_として扱います。すべての財務イベント(取引、勘定開設、商品価格など)はテキストファイル内のディレクティブ(指示)であり、Beancountはこれを解析してエントリーのインメモリデータベースに変換します。この設計により、複式簿記の原則が強制されます。つまり、すべての取引は勘定間で借方と貸方のバランスが取れていなければなりません。その結果、バージョン管理、検査、クエリが容易な、非常に透明性が高く監査可能な台帳が生まれます。

哲学 – 正確性とミニマリズム: Beancountの設計は、データの整合性とシンプルさを優先しています。その作成者であるMartin Blaisは、Beancountがユーザーが間違いを犯すことを前提とした「悲観的」なものであると述べており、そのため追加のチェックと制約を課しています。たとえば、Beancountは一度も追加されていない資産の削除を許可せず(負の株式保有や現金残高を防ぐ)、使用前にすべての勘定が開設されていることを強制できます。Ledgerの「仮想」または自動的にバランスが取られる転記の概念は欠けています。これは、完全にバランスの取れたエントリーを強制するための意図的な選択です。Beancountは、基本的な複式簿記が提供する以上のクロスチェックを行い、事実上**「正確性に徹底的にこだわる」**姿勢をとっています。この慎重なアプローチは、「自分自身をあまり信用していない」ユーザーや、ソフトウェアにエラーを検出してほしいと考えるユーザーにアピールします。
最小限のオプション、最大限の一貫性: Ledgerの無数のコマンドラインフラグやチューニングオプションとは対照的に、Beancountはミニマリズムを選択しています。グローバルオプションは非常に少なく、台帳ファイル外で取引のセマンティクスを変更するものはありません。会計に影響を与えるすべての設定(商品の取得原価計算方法や記帳の前提など)は、ファイル内のディレクティブまたはプラグインを介して行われ、レポートの生成方法に関わらず、同じファイルを読み込むと常に同じ結果が生成されることを保証します。この設計は、Ledgerの多くの調整項目とそれらの間の微妙な相互作用の複雑さを回避します。Beancountの哲学は、会計ツールは入力ファイルからレポートまでの一貫した安定した決定論的なパイプラインであるべきだというものです。これは、台帳をプログラムで順次処理できるディレクティブの順序付きストリームとして扱うことで実現されます。Ledgerが特別な構文として扱うもの(期首残高や価格ステートメントなど)でさえ、Beancountのデータモデルでは第一級のディレクティブであり、これがシステムを非常に拡張性の高いものにしています。
プラグインとクエリ言語による拡張性: BeancountはPythonで実装されており、処理パイプラインにカスタムロジックを注入するためのフックを提供します。ユーザーは、取引のストリーム上で動作するPythonのプラグインを作成できます(たとえば、カスタムルールを強制したり、自動エントリーを生成したりするため)。これらのプラグインはファイルが処理される際に実行され、ソースを変更することなくBeancountのコア機能を効果的に拡張します。Beancountには、台帳を分析するための強力なクエリ言語(SQLに触発されたもの)も含まれています。bean-query
ツールは、解析された台帳をデータベースとして扱い、分析クエリを実行できます。たとえば、カテゴリ別に費用を合計したり、特定の受取人のすべての取引を抽出したりできます。Beancount 3.xでは、このクエリ機能はスタンドアロンのbeanquery
パッケージに移動しましたが、ユーザーの観点からは、依然としてSQLライクなクエリを介して柔軟なレポート作成が可能です。
プレーンテキストとバージョン管理: プレーンテキスト会計ツールとして、Beancountは_ユーザーコントロール_とデータの永続性を重視しています。台帳は単なる.beancount
テキストファイルであり、どのテキストエディタでも編集できます。これは、あなたの全財務履歴が人間が読める形式で保存され、Gitや他のVCSに入れて変更を時系列で追跡できることを意味します。ユーザーはしばしば、すべての編集の監査証跡を維持するために(変更を説明するコミットメッセージと共に)Beancountファイルをバージョン管理下に置きます。このアプローチは、会計データ、特に個人や小規模ビジネスの財務は、透明で「将来も利用可能」であるべきだというBeancountの哲学と一致しています。つまり、独自のデータベースにロックされるべきではないということです。Martin Blais自身の言葉を借りれば、Beancountはコミュニティのためにシンプルで、永続的で、無料であるように作られた「愛情のこもった労働」です。それは2007年頃に最初に開発され、主要な書き直し(v1からv2、そして2024年のv3)を経て、ミニマリズムと正確性というコア哲学を維持しながら設計を洗練させてきました。
Beancountエコシステムのツール、プラグイン、拡張機能
Beancountエコシステムは、コアの台帳機能を強化する豊富なツール、プラグイン、拡張機能のセットを成長させてきました。これらは、データのインポート、台帳の編集、レポートの表示、特殊な会計機能の追加をカバーしています。以下に、Beancountの世界における主要なコンポーネントとアドオンの概要を示します:
データインポートユーティリティ(インポーター)
実用的な使用において最も重要なニーズの一つは、銀行、クレジットカード、その他の金融機関から取引をインポートすることです。Beancountはこの目的のためにインポートフレームワークとコミュニティ提供のインポートスクリプトを提供しています。Beancount 2.xでは、組み込みモジュールbeancount.ingest
(bean-extract
やbean-identify
などのコマンドを含む)がPythonでインポータープラグインを定義し、ダウンロードした明細書に適用するために使用されていました。Beancount 3.xでは、これはBeangulpという外部プロジェクトに置き換えられました。Beangulpはbeancount.ingest
から進化した専用のインポーターフレームワークであり、現在Beancount 3.0の取引インポートを自動化するための推奨方法となっています。これにより、外部ファイル(CSVやPDF明細書など)を読み取り、Beancountのエントリーを出力するPythonスクリプトやコマンドラインツールを作成できます。この新しいアプローチは、インポートロジックをBeancountのコアから切り離します。たとえば、古いbean-extract
コマンドはv3で削除され、代わりにインポートスクリプト自体がBeangulpのCLIインターフェースを介して取引を生成します。
コミュニティによって提供された、さまざまな銀行やフォーマットに対応する既製のインポーターが数十も存在します。中国のAlipayやWeChat Payから、ヨーロッパの各種銀行(Commerzbank, ING, ABN AMROなど)、ChaseやAmexのような米国の銀行まで、世界中の金融機関向けのインポータースクリプトがあります。これらの多くは公開リポジトリ(多くはGitHub上)やbeancount-importers
のようなパッケージに集められています。例えば、Tarioch Beancount Toolsプロジェクト(tariochbctools
)は、スイスや英国の銀行向けのインポーターを提供し、暗号資産取引のインポートも処理します。別の例としてLazy Beancountは、一般的なインポーター(Wise, Monzo, Revolut, IBKRなど)のセットをパッケージ化し、簡単な自動化のためのDockerベースのセットアップを提供します。どの銀行や金融サービスを利用していても、誰かがそのためのBeancountインポーターを書いている可能性があります。そうでなくても、Beangulpのフレームワークを使えば自分で書くことができます。Pythonの柔軟性により、インポーターはCSV/Excelファイルの解析、OFX/QIFダウンロードの処理、さらにはAPIのスクレイピングを行い、標準化されたBeancount形式で取引を出力できます。
編集とエディタ統合
Beancountの台帳は単なるテキストであるため、ユーザーは好みのテキストエディタやIDEを活用して管理することがよくあります。エコシステムは、この体験をよりスムーズにするためのエディタサポートプラグインを提供しています。多くの人気エディタには、シンタックスハイライト、勘定科目名の自動補完、リアルタイムのエラーチェックを追加する拡張機能があります:
- Emacs Beancount-Mode: Emacsのメジャーモード(
beancount-mode
)が利用可能で、.beancountファイルの編集をサポートし、シンタックスカラーリングやBeancountのチェッカーとの統合などの機能を提供します。バックグラウンドでbean-check
を実行することもでき、編集中に 台帳のエラー(バランスの取れていない取引など)がフラグ付けされます。
- VS Code拡張機能: VSCode MarketplaceにあるBeancount拡張機能は、Visual Studio Codeユーザーに同様の利便性を提供します。シンタックスハイライト、金額の桁揃え、勘定科目/受取人の自動補完、さらにはファイル保存時のオンザフライでの残高チェックをサポートしています。Favaとの統合も可能で、VSCode内からFavaのWebインターフェースを起動できます。
- Vim、Atom、その他のエディタ用にもプラグインやモードが存在します。例えば、Beancount用のTree-sitter文法があり、これは現代のエディタでシンタックスハイライトを強化し、FavaのWebベースのエディタコンポーネントでも採用されました。要するに、あなたの編集環境が何であれ、コミュニティはBeancountファイルの編集を便利でエラーのないものにするためのプラグインを提供している可能性が高いです。
従来のエディタ以外での迅速な取引入力のために、Bean-addやモバイルアプリのようなツールもあります。_Bean-add_は、プロンプトやワンライナーで新しい取引を追加できるコマンドラインツールで、日付や勘定の提案を処理します。モバイルでは、Beancount Mobileというプロジェクトが、外出先で取引を入力するためのシンプルなインターフェースを提供します(例えば、携帯電話から現金の購入を記録するなど)。さらに、メッセージングを通じて取引を記録するためのBeancount Telegram Botも存在します。取引詳細を含むメッセージを送信すると、ボットがそれを台帳ファイルにフォーマットし ます。
Webフロントエンドと可視化ツール
(Fava) Favaのウェブインターフェースは、Beancount用のインタラクティブなダッシュボードを提供し、勘定科目と残高のテーブルと共に、可視化(ここではカテゴリ別の費用のツリーマップとして表示)を伴う損益計算書などのレポートを特徴としています。
Beancountの代表的なフロントエンドは、モダンなWebインターフェースであるFavaです。Favaは、あなたのBeancountファイルを読み取り、ブラウザでリッチなインタラクティブ体験を生成するローカルWebアプリとして動作します。貸借対照表、損益計算書、時系列の純資産、ポートフォリオ保有状況、パフォーマンスチャート、予算など、豊富なレポート一式を標準で提供します。ユーザーはしばしば、他のプレーンテキスト会計ツールよりもBeancountを選ぶ大きな理由としてFavaを挙げます。たった一つのコマンド(fava ledger.beancount
)で、テキストの代わりにグラフやテーブルで財務状況を閲覧できます。Favaは次のような機能をサポートしています:勘定のドリルダウン、受取人やタグによる取引のフィルタリング、クエリエディタ(Beancountクエリを実行し、ブラウザで結果を確認できる)、さらには台帳用の統合されたWebベースのエディタまで。非常に使いやすく、視覚的なインターフェースを好む人々にとってプレーンテキスト会計を身近なものにしています。
内部的には、FavaはPython(バックエンドはFlask)とJavaScript(フロントエンドはSvelte)で書かれています。独自のリリースサイクルを持ち、活発にメンテナンスされています。特筆すべきは、FavaがBeancountの開発に追随している点です。たとえば、Fava 1.30ではBeancount v3のサポートが追加され、内部で新しいbeanquery
およびbeangulp
パッケージを使用するように切り替わりました。(古い台帳のためにBeancount 2も引き続きサポートしています。)Favaの使いやすさへの注力には、Webエディタでの自動補完や、ダークモードとレスポンシブなチャートを備えた洗練されたUIなどが含まれます。また、Fava-GTKという派生プロジェクトもあり、これはネイティブアプリの感触を好むGNOME/LinuxユーザーのためにFavaをデスクトップアプリケーションとしてパッケージ化したものです。
Fava以外にも、他の可視化・分析オプションが存在します。Beancountのデータはテーブルとしてエクスポートまたはクエリできるため、ユーザーはJupyterノートブックやPandasのようなツールをカスタム分析に活用することがよくあります。例えば、あるユーザーは、カスタムレポートを準備するためにクエリインターフェース経由でBeancountからPandasのDataFrameにデータを引き出す方法を説明しています。特定のレポート用のコミュニティ提供スクリプトもあります。例えば、ポートフォリオ配分分析ツールや、支出対純資産の工程管理図などです。しかし、ほとんどの人にとって、Favaはコードを書かなくても十分すぎるほ どのレポート機能を提供します。さらには拡張機能もサポートしており、新しいレポートページやチャートをFavaに追加するPythonファイルをドロップインできます。注目すべき拡張機能は、Fava内でエンベロープ予算管理を行うためのfava-envelopeです。全体として、FavaはBeancountエコシステムの中心的な可視化ハブとして機能しています。
コマンドラインユーティリティとスクリプト
Beancountには様々なCLIツールが付属しています(特に古いv2ブランチに多く、一部はv3で整理されました)。これらのツールは、台帳ファイルを操作してチェックしたり、テキストやHTMLで特定のレポートを生成したりします:
- bean-check: ファイルの構文エラーや会計エラーをチェックするバリデータ。
bean-check myfile.beancount
を実行すると、不均衡、勘定の欠落、その他の問題が警告され、ファイルがエラーフリーであれば何も出力されません。
- bean-format: ソースコードにコードフォーマッタをかけるように、数値をきれいな列に揃えて台帳を整えるフォーマッタ。これにより、ファイルがクリーンで読みやすくなります。
- bean-query: 台帳に対してBeancountのクエリ言語を実行するための対話型シェルまたはバッチツール。カスタムの表形式 レポートを作成するために使用できます(例:
bean-query myfile.beancount "SELECT account, sum(amount) WHERE ..."
)。
- bean-report: (v2の)多機能レポートジェネレータで、定義済みのレポート(貸借対照表、損益計算書、試算表など)をコンソールやファイルに出力できます。例えば、
bean-report file.beancount balances
は勘定残高を出力します。(実際には、これらのテキストレポートの多くはFavaのより優れた表示に取って代わられています。)
- bean-web / bean-bake:
localhost
でレポートを提供したり、静的なHTMLファイルとして「ベイク」したりする古いWebインターフェース。これらはFavaが人気になる前に主に使用されていました。bean-webは、bean-reportが生成できるのと同じレポートの基本的なWebビューを提供していました。Beancount 3では、bean-webは削除されました(Favaが推奨されるWebフロントエンドとなり、優れた体験を提供するため)。
- bean-example: サンプルの台帳ファイルを生成するユーティリティ(新規ユーザーがBeancountエントリーのテンプレートを見るのに便利)。
- bean-doctor: 台帳や環境の問題を診断できるデバッグツール。
Beancount v3の時点で、これらのツールの多くがコアプロジェクトから移動されたことは注目に値します。コアのBeancountパッケージは効率化され、クエリエンジンやインポーターのようなツールはメンテナンスを容易にするために別々のパッケージ(beanquery, beangulpなど)に分割されました。例えば、bean-queryの機能は現在、別途インストールされるbeanquery
ツールによって提供さ れます。ユーザーの観点からは、機能は引き続き利用可能ですが、モジュール化されただけです。Arch LinuxコミュニティはFavaを更新する際にこの変更に注目しました:FavaパッケージはBeancount 3.xをサポートするためにbeanqueryとbeangulpへの依存関係を追加しました。このモジュール化アプローチにより、コミュニティの他の人々がBeancountのリリースサイクルとは独立してこれらの補助ツールに貢献することも可能になります。
Beancountプラグインと拡張機能
Beancountエコシステムの際立った強みはプラグインシステムです。Beancountファイルにplugin "module.name"
という行を追加することで、台帳処理中に実行されるカスタムPythonロジックを組み込むことができます。コミュニティはBeancountの機能を拡張するために多くのプラグインを作成しました:
- データ品質とルール: 例として、複数の勘定を含む方程式をアサートできる
beancount-balexpr
(例:資産A + 資産B = 負債X)、勘定を閉鎖する際に自動的に残高アサーションを挿入してゼロになることを保証するbeancount-checkclosed
があります。ファイル内の取引が日付順にソートされていることを保証するプラグイン(autobean.sorted
)もあり、順序が違うエントリーを検出します。
- 自動化:
beancount-asset-transfer
プラグインは、勘定間で現物移管のエントリーを生成できます(取得原価を維持したままブローカー間で株式を移動するのに便利)。別のautobean.xcheck
は、Beancount台帳を外部の明細書と相互チェックして不一致を見つけます。
- 繰り返し取引と予算: Akuukisによる**「repeat」または補間プラグインは、繰り返し取引を定義したり、年間の費用を月々に分割したりすることができます。予算管理については、
fava-envelope
拡張機能(Fava経由で使用)がプレーンテキストでのエンベロープ予算管理手法をサポートします。また、Frank DaviesによるMiniBudget**もあります。これは、個人や小規模ビジネスの予算管理を支援するためにBeancountに触発された小さなスタンドアロンツールです。
- 税務とレポート: 税務会計を支援するプラグインもあります。例えば、キャピタルゲインを自動的に短期と長期に分類するものなどです。別のプラグイン(Justus Pendletonによる
fincen_114
)は、外国口座を持つ米国納税者向けのFBARレポートを生成し、Beancountデータが規制報告にどのように活用できるかを示しています。
- コミュニティプラグインリポジトリ: beancount-plugins(Dave Stephensによる)のようなキュレーションされたプラグインセットがあり、減価償却エントリーなどに焦点を当てています。また、beancount-plugins-zack(Stefano Zacchiroliによる)には、ディレクティブのソートなどの様々なヘルパーが含まれています。
プラグインに加えて、Beancountを取り巻く他のユーティリティツールは特定のニーズに対応しています。例えば、beancount-blackは、Blackコードフォーマッタに似た自動フォーマッタですが、Beancount台帳ファイル用です。前述のように、チャット経由で取引を追加するためのBeancount Bot(Telegram/Mattermost)や、macOSですばやくファイルに取引を追加するためのAlfredワークフローがあります。Pintoという名前のツールは、対話的な入力(強化版bean-addのようなもの)を備えた「超強化された」CLIを提供します。他のシステムから移行する人のために、コンバータも存在します(YNAB2Beancount、CSV2Beancount、GnuCash2Beancount、Ledger2Beancount)
。
要約すると、Beancountエコシステムは非常に広範です。以下の表1は、いくつかの主要なツールと拡張機能をその役割とともにリストアップしたものです:
ツール/拡張機能 | 説明 |
---|
Fava (Webインターフェース) | Beancountの帳簿を閲覧・編集するためのフル機能のWebアプリ。インタラクティブなレポート(貸借対照表、損益計算書など)、チャート、クエリ機能を提供。Beancountの使いやすさを大幅に向上させる。 |
Beangulp (インポートフレームワーク) | Beancount v3用のスタンドアロンインポーターフレームワークで、古いingestモジュールを置き換える。プラグインスクリプトを使用して銀行明細書(CSV、PDFなど)をBeancountエントリーに変換するのに役立つ。 |
Beanquery (クエリツール) | Beancountデータ用のスタンドアロンSQLライククエリエンジン。v3でbean-query を置き換え、使い慣れたSELECT-FROM-WHERE構文で取引や残高の高度なクエリを可能にする。 |
Bean-check / Bean-format | Beancountファイルを検証し(エラーをチェック)、一貫性のために自動フォーマットするコアCLIツール。正確でクリーンな台帳を維持するのに役立つ。 |
エディタプラグイン (Emacs, VSCode, Vimなど) | テキストエディタにBeancountのシンタックスサポートとリンティングを追加するプラグイン/モード。.beancountファイルの手動編集体験を、自動補完やライブエラーハイライトなどの機能で向上させる。 |
コミュニティインポーター | 米国、EU、アジアなどの銀行をカバーする銀行インポートスクリプトのコレクション(多くはGitHub上にある)。ユーザーが金融機関から取引を自動的にBeancountに取り込むことを可能にする。 |
プラグイン (台帳拡張機能) | ルールを強制したり機能を追加したりするためのオプションのファイル内プラグイン(例:経費分担、繰り返しエントリー、カスタム残高アサーション)。Pythonで書かれ、カスタマイズのためにファイル処理中に実行される。 |
コンバータ (移行ツール) | 他のフォーマット(例:GnuCashやLedger CLI)からBeancountフォーマットへデータを変換するユーティリティ。ゼロから始めることなくBeancountを採用するのを容易にする。 |
Ledger、hledger、および類似システムとの比較