# Awesome Beancount

A curated guide to the Beancount ecosystem. Beancount is a powerful, open-source accounting system that uses a simple, text-based format to manage your finances with the rigor of double-entry bookkeeping. This page combines community-curated lists and ecosystem overviews into one comprehensive resource.

## Why Plain Text Accounting?

Plain text accounting (PTA) is a methodology for managing finances using simple text files and powerful command-line tools. This approach gives you full ownership of your data, ensures longevity, and offers unparalleled flexibility for automation and analysis.

- **Official PTA Hub:** [Plain Text Accounting](https://plaintextaccounting.org/)
- **A Gentle Introduction:** [Accounting for the simple minds with plain text accounting](https://dustri.org/b/accounting-for-the-simple-minds-with-plain-text-accounting.html)
- **From Web Apps to CLI:** [Command line accounting: From mint.com to Ledger](https://muehe.org/posts/command-line-accounting/)

***

## The Beancount Ecosystem

The Beancount ecosystem is a collection of tools, plugins, and resources built around a core engine. Each component plays a specific role in creating a complete financial management workflow.

### 1. Core Engine & Official Resources

These are the foundational elements of Beancount, maintained by the creator and official contributors.

| Resource                   | Description                                                                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Beancount (Core)**       | The engine that reads your ledger file, enforces double-entry rules, and generates reports. It provides core command-line utilities like `bean-check` and `bean-format`. All other tools are built on this. |
| **Homepage**               | [beancount.github.io](https://beancount.github.io/)                                                                                                                                                         |
| **Source Code**            | [github.com/beancount/beancount](https://github.com/beancount/beancount)                                                                                                                                    |
| **Documentation**          | [GitHub Pages](https://beancount.github.io/docs/) and [Google Docs](https://docs.google.com/document/d/1RaondTJCS_IUPBHFNdT8oqFKJjVJDsfsn6JEjBG04eA/edit)                                                   |
| **External Contributions** | [Official list of community contributions](https://beancount.github.io/docs/external_contributions.html)                                                                                                    |
| **Beanquery**              | A powerful, SQL-like query tool (`v3`) for running advanced queries (e.g., `SELECT ... FROM ... WHERE ...`) against your ledger to generate custom analyses.                                                |

### 2. User Interfaces

These tools provide visual interfaces for exploring and editing your financial data.

| Tool                       | Description                                                                                                                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fava**                   | The definitive, full-featured web dashboard for Beancount. It provides interactive charts, drill-down tables, in-browser editing, and an extension system for adding features like budgeting. |
| **Fava-GTK**               | A native GNOME Desktop application that wraps Fava for a seamless desktop experience.                                                                                                         |
| **Beancount Mobile**       | A mobile data-entry app for adding transactions on the go.                                                                                                                                    |
| **Beancount Telegram Bot** | A Telegram bot for quickly adding transactions to your ledger via chat.                                                                                                                       |

### 3. Transaction Importing

Importing is the process of converting data from financial institutions (like bank CSVs or PDFs) into Beancount entries.

| Tool                        | Description                                                                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Beangulp (v3)**           | The modern, standalone framework for building importers. It processes external files through Python scripts (plugins) to generate Beancount directives. |
| **Smart Importer**          | A tool that augments importers with machine learning to automatically predict and assign categories.                                                    |
| **Beancount Reds Ingestor** | A collection of importers with a common library for handling CSV and OFX files.                                                                         |
| **double-entry-generator**  | A rule-based importer focused on Chinese services like Alipay and WeChat Pay.                                                                           |

#### Community Importers (By Country)

A vast collection of scripts for specific banks and services, maintained by the community.

- **China**

  - Alipay / 支付宝: [deb-sig/double-entry-generator](https://github.com/deb-sig/double-entry-generator), [wzyboy/importer](https://github.com/wzyboy/awesome-beancount/blob/master/importers/alipay_acclog.py)
  - China Merchants Bank (CMB): [Debit Card](https://github.com/wzyboy/awesome-beancount/blob/master/importers/cmb_debit_cards.py), [Credit Card](https://github.com/wzyboy/awesome-beancount/blob/master/importers/cmb_credit_cards.py)
  - WeChat Pay / 微信支付: [deb-sig/double-entry-generator](https://github.com/deb-sig/double-entry-generator)

- **France**

  - Caisse d'Epargne: [beancount-ce](https://github.com/ArthurFDLR/beancount-ce)
  - Boursorama, Amex: [Beancount-myTools](https://github.com/grostim/Beancount-myTools)

- **Germany**

  - Commerzbank: [beancount-commerzbank](https://github.com/siddhantgoel/beancount-commerzbank)
  - Deutsche Kredit Bank (DKB): [beancount-dkb](https://github.com/siddhantgoel/beancount-dkb)
  - ING: [beancount-ing](https://github.com/siddhantgoel/beancount-ing)
  - N26: [beancount-n26](https://github.com/siddhantgoel/beancount-n26)
  - Volksbank & GLS-Bank: [beancount-importer-volksbank](https://github.com/Fjanks/beancount-importer-volksbank)

- **India**
  - SBI, BOI, Paytm, HSBC, ICICI: [beancount-importers-india](https://github.com/dumbPy/beancount-importers-india)

- **Netherlands**
  - ABN AMRO: [beancount-abnamro](https://github.com/deepakg/beancount-abnamro)

- **Switzerland**

  - General: [tariochbctools](https://tariochbctools.readthedocs.io/) (BCGE, Neon, Raiffeisen, ZKB, Fidelity)
  - Finpension: [drnuke-bean](https://github.com/Dr-Nuke/drnuke-bean?tab=readme-ov-file#finpension-importer)
  - PostFinance: [tariochbctools](https://github.com/tarioch/beancounttools/blob/master/src/tariochbctools/importers/postfinance/importer.py), [drnuke-bean](https://github.com/Dr-Nuke/drnuke-bean?tab=readme-ov-file#postfinance-importer-swiss)

- **UK**

  - Monzo, Revolut, Wise: [Evernight/beancount-importers](https://github.com/Evernight/beancount-importers/)
  - Revolut, Wise: [tariochbctools](https://tariochbctools.readthedocs.io/en/latest/importers.html#revolut)

- **US**

  - Amex, Chase, Citi, Schwab: [mterwill/gist](https://gist.github.com/mterwill/7fdcc573dc1aa158648aacd4e33786e8#file-importers-amex-py)
  - Capital One: [mtlynch/beancount-capitalone](https://github.com/mtlynch/beancount-capitalone)
  - Chase: [mtlynch/beancount-chase-bank](https://github.com/mtlynch/beancount-chase-bank), [ArthurFDLR/beancount-chase](https://github.com/ArthurFDLR/beancount-chase)
  - Clipper: [beancount-clipper](https://git.sr.ht/~goorzhel/beancount-clipper)
  - Mercury: [mtlynch/beancount-mercury](https://github.com/mtlynch/beancount-mercury)

- **Blockchain**
  - [tariochbctools](https://tariochbctools.readthedocs.io/en/latest/importers.html#blockchain)

### 4. Editor Support & Tooling

Tools that integrate Beancount into your development environment to streamline editing and maintenance.

- **IDE Support:** Plugins providing syntax highlighting, auto-completion, and on-the-fly balance checking.

  - [VSCode](https://marketplace.visualstudio.com/items?itemName=Lencerf.beancount)
  - [Emacs](https://github.com/beancount/beancount-mode)
  - [Vim](https://github.com/nathangrigg/vim-beancount)
  - [Zed](https://github.com/zed-extensions/beancount)
  - [Sublime Text](https://github.com/norseghost/sublime-beancount)
  - [Atom](https://atom.io/packages/beancount)
  - [Beancount Language Server](https://github.com/polarmutex/beancount-language-server) (for any LSP-compatible editor)

- **Automation & Utilities:**

  - `bean-add`: Interactively add transactions from the command line.
  - `beancount-black`: An opinionated code formatter for Beancount files.
  - `beancount-categorizer`: Automatically categorize transactions with regex rules.
  - `beanahead`: Administer and project future transactions.

- **Data Migration Tools:** Utilities to convert data from other accounting systems.

  - From GnuCash: [henriquebastos/gc-to-bc](https://github.com/henriquebastos/gnucash-to-beancount/), [dtrai2/gc-to-bc](https://github.com/dtrai2/gnucash-to-beancount/)
  - From Ledger/hledger: [travisdahlke/gist](https://gist.github.com/travisdahlke/71152286b0a8826249fe), [zacchiro/ledger2beancount](https://github.com/zacchiro/ledger2beancount)
  - From YNAB: [hoostus/beancount-ynab](https://github.com/hoostus/beancount-ynab)

### 5. Plugins (Ledger Extensions)

In-ledger Python modules that run during processing to enforce custom rules, automate transactions, or add new features.

- **Budgeting:**
  - [fava-envelope](https://github.com/polarmutex/fava-envelope): A Fava extension for envelope-style budgeting.

- **Automation & Checks:**

  - [autobean.share](https://github.com/SEIAROTg/autobean/tree/master/autobean/share): Expense splitting and debt management.
  - [autobean.sorted](https://github.com/SEIAROTg/autobean/tree/master/autobean/sorted): Ensures transactions are chronologically ordered.
  - [beancount-checkclosed](https://github.com/daniel-wells/beancount_checkclosed): Automatically checks for a zero balance on closed accounts.

- **Data Manipulation:**

  - [autobean.narration](https://github.com/SEIAROTg/autobean/tree/master/autobean/narration): Auto-generates transaction narrations.
  - [beancount-lazy-plugins.filter\_map](https://github.com/Evernight/beancount-lazy-plugins/tree/main?tab=readme-ov-file#filter_map): Applies operations to a filtered group of transactions.

### 6. Price Sources

Scripts that fetch historical and current prices for commodities, stocks, and currencies to track investment values.

- [beancount-exchangerates](https://github.com/xuhcc/beancount-exchangerates): For fiat currencies via APIs like `frankfurter.dev`.
- [pricehist](https://gitlab.com/chrisberkhout/pricehist): A multi-source price fetcher.
- [beancount-cryptoassets](https://github.com/xuhcc/beancount-cryptoassets): For fetching cryptocurrency prices.
- [tariochbctools](https://tariochbctools.readthedocs.io/): Includes a price source for Interactive Brokers.

***

## Learning & Community

### Books & In-Depth Guides

- **Tracking Personal Finances using Python:** A book that provides a comprehensive guide to building a personal finance system with Beancount. ([Website](https://personalfinancespython.com/))
- **Chinese Blog Series (BYVoid):** [Part 1: Why?](https://byvoid.com/zhs/blog/beancount-bookkeeping-1), [Part 2: Debits & Credits](https://byvoid.com/zhs/blog/beancount-bookkeeping-2)

### Selected Blog Posts

- **English**

  - [Counting beans - and more - with Beancount](https://lwn.net/Articles/751874/)
  - [Managing Personal Finances using Python](https://sgoel.dev/posts/managing-personal-finances-using-python/)
  - [No-Bullshit Beancount Introduction](https://web.archive.org/web/20221119110728/https://blog.leononame.dev/2019/08/beancount/)

- **French**
  - [Beancount ou la comptabilité pour les hackers](https://cyril.deguet.com/fr/2015/09/03/beancount-comptabilite-pour-hackers/)

- **Chinese**
  - [Beancount —— 命令行复式簿记](https://wzyboy.im/post/1063.html)

### Community

- **Mailing List:** [Google Groups](https://groups.google.com/g/beancount) (Primary discussion forum)
- **Live Chat (IRC):** [#beancount on web.libera.chat](https://web.libera.chat/gamja/?channels=%23beancount)
- **Telegram (Chinese):** [t.me/beancount\_zh](https://t.me/beancount_zh)

***

## Commercial Services & Apps

For users who want the power of Beancount without managing the infrastructure themselves.

| Service          | Description                                                                                                                                                                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Beancount.io** | A SaaS (Software as a Service) platform providing an out-of-the-box Beancount and Fava instance. It also offers dedicated mobile apps for [iOS](https://apps.apple.com/app/id1527950512) and [Android](https://play.google.com/store/apps/details?id=io.beancount.android). |

## Put plain text to work.

Start a Beancount ledger, or follow the guide to build your own setup.

[Get Started Free](https://beancount.io/sign-up/?next=%2Fledger%2F) [Getting started guide](https://beancount.io/docs/getting-started)

## Where to look next

- [Sitemap](https://beancount.io/sitemap.xml) - all pages with hreflang alternates
- [LLMs index](https://beancount.io/llms.txt) - curated links for AI agents (also /llms-full.txt for full docs)
- [Documentation](https://beancount.io/docs) - every doc is also available as text/markdown via .md suffix or Accept negotiation
- [REST API reference](https://beancount.io/docs/api-reference) - interactive endpoints, schemas, authentication, and code samples
- [OpenAPI spec](https://beancount.io/openapi.json) - OpenAPI 3.1 spec for this website's public content endpoints; the product contract for ledger operations is at https://beancount.io/api-gateway/v1/openapi.json
- [GraphQL](https://beancount.io/graphql) - public, read-only content API over the blog and research logs (no credentials, no ledger data): 12 query fields over 23 types
- [MCP server](https://beancount.io/mcp) - Model Context Protocol at https://beancount.io/api-gateway/mcp
