External Contributions to Beancount

Martin Blais - Updated: June 2024

http://furius.ca/beancount/doc/contrib

Links to codes written by other people that build on top of or that are related to Beancount and/or Ledgerhub.

Indexes

This document contains only packages that were discussed or have had an announcement sent to the mailing-list. You will be able to find other packages on public indices:

• PyPI: You can find a lot of other Beancount-related projects at PyPI.

• GitHub: A search for "beancount" as of September 2020 brings up 318 projects.

Books and Articles

Managing Personal Finances using Python (Siddhant Goel): a 2020 book on plain-text accounting, and Beancount.

The Five Minute Ledger Update (RedStreet) A series of articles showing how to automate downloading data from institutions (banks, credit cards, brokerages, etc.) so that ledger updates can be done in under five minutes. Mailing list thread.

Tax Loss Harvesting with Beancount (RedStreet): An article about TLH from a US perspective, includes requirements, wash sale subtleties and safe to sell/buy dates, and comparisons to robo-advisors. (Related: fava_investor TLH module. for fava and plain-beancount command line version).

Scaled Estimates of Mutual Fund NAVs (RedStreet) : Problem: Mutual fund NAVs (at least in the US) are updated exactly once per day, at the end of the day. When needing to make financial decisions when the trading window is still open (eg: when tax loss harvesting), and the end-of-day NAV is not yet available, it is sometimes useful to make a trivial estimate of that NAV, especially on days when there are huge changes in the market.

A Shortcut to Scrape Trade History from Fidelity (David Avraamides) I wrote up a description of how I use a Shortcut to scrape trade history from Fidelity’s website, run it through a Python script to convert to Beancount’s ledger format, and then save it in the clipboard so I can paste it into a ledger file.

Lazy Beancount (Vasily M) / Evernight/lazy-beancount : Opinionated guide on how to start (and continue) tracking personal finances using the open-source Beancount accounting system. It comes together with some code. The primary goal of this guide is to provide you a way to start managing your own finances using plain-text accounting gradually and incrementally. Also with various useful tools already included and set up.

The Zen of Balance — https://academy.beanhub.io/ (Fang-Pen Lin) : An explanation of double-entry accounting using visualizations and diagrams.

Multiperiod hledger-Style Reports in beancount: Pivoting a Table | Altynbek Isabekov : An article showing how to produce pivot table summaries of account balances, e.g. by year, with associated code (github).

Plugins

split_transactions: Johann Klähn wrote a plugin that can split a single transaction into many against a limbo account, as would be done for depreciation.

zerosum: Red S wrote a plugin to match up transactions that when taken together should sum up to zero and move them to a separate account.

effective_dates: Red S wrote a plugin to book different legs of a transaction to different dates

beancount-plugins: Dave Stephens created a repository to share various of his plugins related to depreciation.

beancount-plugins-zack: Stefano Zacchiroli created this repository to share his plugins. Contains sorting of directives and more.

beancount-oneliner: Akuukis created a plugin to write an entry in one line (PyPi).

beancount-interpolate: Akuukis created plugins for Beancount to interpolate transactions (recur, split, depr, spread) (PyPi).

metadata-spray: Add metadata across entries by regex expression rather than having explicit entries (by Vivek Gani).

Akuukis/beancount_share: A beancount plugin to share expenses among multiple partners within one ledger. This plugin is very powerful and most probably can deal with all of your sharing needs.

w1ndy/beancount_balexpr (Di Weng): A plugin that provides "balance expressions" to be run against the Beancount entries, as a Custom directive. See this thread.

autobean.narration (Archimedes Smith): Allows to annotate each posting in a concise way by populating per-posting narration metadata from inline comments.

autobean.sorted: Checks that transactions are in non-descending order in each file. Helps identifying misplaced or misdated directives, by warning on those directives not following a non-descending order by date in the file.

hoostus/beancount-asset-transfer-plugin: A plugin to automatically generate in-kind transfers between two beancount accounts, while preserving the cost basis and acquisition date.

PhracturedBlue/fava-portfolio-summary (Phractured Blue): Fava Plugin to show portfolio summaries with rate of return.

rename_accounts: Plugin from Red S to rename accounts. E.g.: rename “Expenses:Taxes” to “Income:Taxes” is helpful for expense analysis. More here.

Long_short capital gains classifier: Plugin from Red S to classify capital gains into long and short based on duration the assets were held, and into gains and losses based on value.

Autoclose_tree: Automatically closes all of an account's descendants when an account is closed.

Evernight/beancount-valuation (Vasily M) : A Beancount plugin to track total value of the opaque fund. You can use it instead of the balance operation to assert total value of the account. If the value of the account is currently different, it will instead alter price of the underlying synthetical commodity created by the plugin used for technical purposes.

Tools

alfred-beancount (Yue Wu): An add-on to the “Alfred” macOS tool to quickly enter transactions in one’s Beancount file. Supports full account names and payees match.

bean-add (Simon Volpert): A Beancount transaction entry assistant.

hoostus/fincen_114 (Justus Pendleton): An FBAR / FinCEN 114 report generator.

ghislainbourgeois/beancount_portfolio_allocation (Ghislain Bourgeois): A quick way to figure out the asset allocations in different portfolios.

hoostus/portfolio-returns (Justus Pendleton): portfolio returns calculator

costflow/syntax (Leplay Li): A product that allows users to keep plain text accounting from their favorite messaging apps. A syntax for converting one-line message to beancount/*ledger format.

process control chart (Justus Pendleton): Spending relative to portfolio size. Thread.

Pinto (Sean Leavey): Supercharged command line interface for Beancount. Supports automatic insertions of transactions in ledger file.

PhracturedBlue/fava-encrypt : A docker-base solution for keeping Fava online while keeping beancount data encrypted at rest. See this thread for context.

kubauk/beancount-import-gmail : beancount-import-gmail uses the gmail API and OAuth to log into your mailbox and download order details which are then used to augment your transactions for easier classification.

sulemankm/budget_report : A very simple command-line budget tracking tool for beancount ledger files.

fdavies93/minibudget (Frank Davies): MiniBudget is a tool designed to enable personal and small business budgeting using a plaintext format. It's inspired by beancount and plainbudget.

dyumnin/dyu_accounting : Accounting setup to automate generation of various financial statements for Compliance with Indian Govt.

Gains Minimizer (RedStreet): Automatically determine lots to sell to minimize capital gains taxes. Live example.

beanahead (Marcus Read): Adds the ability to include future transactions (automatically generates regular transactions, provides for ad hoc expected transactions, expected transactions are reconciled against imported transactions; all functionality accessible via cli).

autobean-format (Archimedes Smith): Yet another formatter for beancount,, powered by earlier project autobean-refactor, a library for parsing and programmatically manipulating beancount files. based on a proper parser, allowing it to format every corner of your ledger, including arithmetic expressions.

akirak/flymake-bean-check (Akira Komamura): flymake support for Emacs.

bean-download (Red Street): A downloader that ships with beancount-reds-importers that you can configure to run arbitrary commands to download your account statements. It now has a new feature: the needs-update subcommand.

gerdemb/beanpost (Ben Gerdemann): Beanpost consists of a PostgreSQL schema and import/export commands that let you transfer data between a beancount file and a PostgreSQL database. Much of Beancount's functionality is implemented using custom PostgreSQL functions, allowing for complex queries and data manipulation. This setup provides a flexible backend that can integrate with other tools like web apps or reporting systems

LaunchPlatform/beanhub-cli (Fang-Pen Lin): Command line tools for BeanHub or Beancount users.

zacchiro/beangrep : Beangrep is a grep-like filter for the Beancount plain text accounting system.

Alternative Parsers

Bison

The Beancount v2 parser uses GNU flex + GNU bison (for maximum portability).

The Beancount v3 parser uses RE/flex + GNU bison (for Unicode and C++).

Using Antlr

jord1e/jbeancount (Jordie Biemold) / using Antlr: An alternative parser for Beancount input syntax in Java (using the Antlr4 parser generator). This provides access to parsed Beancount data - without the effect of plugins - from JVM languages. See this post for details.

Using Tree-sitter

polarmutex/tree-sitter-beancount (Bryan Ryall): A tree-sitter parser for the Beancount syntax.

https://github.com/dnicolodi/tree-sitter-beancount (Daniele Nicolodi): Another tree-sitter based parser for the Beancount syntax.

In Rust

jcornaz/beancount-parser (Jonathan Cornaz): A beancount file parser library for Rust. Uses nom.

beancount_parser_lima (Simon Guest): A zero-copy parser for Beancount in Rust. It is intended to be a complete implementation of the Beancount file format, except for those parts which are deprecated and other features as documented here (in a list which may not be comprehensive). Uses Logos, Chumsky, and Ariadne.

Emacs Lisp

trs-80/beancount-txn-elisp/ : beancount-txn-elisp: A library to read/parse and write/insert individual Beancount transactions, implemented in Emacs Lisp.

Importers

reds importers: Simple importers and tools for several US based institutions, and various file types. Emphasizes ease of writing your own importers by providing well maintained common libraries for banks, credit cards, and investment houses, and for various file types, which minimizes the institution specific code you need to write. This is a reference implementation of the principles expressed in The Five Minute Ledger Update. Contributions welcome. By RedStreet

plaid2text: An importer from Plaid which stores the transactions to a Mongo DB and is able to render it to Beancount syntax. By Micah Duke.

jbms/beancount-import: A tool for semi-automatically importing transactions from external data sources, with support for merging and reconciling imported transactions with each other and with existing transactions in the beancount journal. The UI is web based. (Announcement, link to previous version). By Jeremy Maitin-Shepard.

awesome-beancount: A collection of importers for Chinese banks + tips and tricks. By Zhuoyun Wei.

beansoup: Filippo Tampieri is sharing some of his Beancount importers and auto-completer in this project.

montaropdf/beancount-importers: An importer to extract overtime and vacation from a timesheet format for invoicing customers.

siddhantgoel/beancount-dkb (Siddhant Goel): importer for DKB CSV files.

prabusw/beancount-importer-zerodha: Importer for the Indian broker Zerodha.

swapi/beancount-utils : Another importer for Zerodha.

Dr-Nuke/drnuke-bean (Dr Nuke): An importer for IBKR, based on the flex query (API-like) and one for Swiss PostFinance.

Beanborg (Luciano Fiandesio): Beanborg automatically imports financial transactions from external CSV files into the Beancount bookkeeping system.

szabootibor/beancount-degiro (PyPI): Importer for the trading accounts of the Dutch broker Degiro.

siddhantgoel/beancount-ing-diba (PyPI): ING account importer (NL).

PaulsTek/csv2bean : Asimple application to preprocess csv files using google sheets in Go.

ericaltendorf/magicbeans (Eric Altendorf): Beancount importers for crypto data. Detailed lot tracking and capital gains/losses reporting for crypto assets. " I wrote it because I was not satisfied with the accuracy or transparency of existing commercial services for crypto tax reporting."

OSadovy/uabean (Oleksii Sadovyi): A set of Beancount importers and scripts for popular Ukrainian banks and more.

fdavies93/seneca (Frank Davies): Importer for Wise. Multi-currency transfers.

LaunchPlatform/beanhub-import : New beancount importer with a UI.

rlan/beancount-multitool (Rick Lan): Beancount Multitool is a command-line-interface (CLI) tool that converts financial data from financial institutions to Beancount files (supported: JA Bank ＪＡネットバンク, Rakuten Card 楽天カード, Rakuten Bank 楽天銀行, SBI Shinsei Bank 新生銀行). Associated post: https://www.linkedin.com/feed/update/urn:li:activity:7198125470662500352/

LaunchPlatform/beanhub-import (Fang-Pen Lin): Beanhub-import is a simple, declarative, smart, and easy-to-use library for importing extracted transactions from beanhub-extract. It generates Beancount transactions based on predefined rules.

Converters

plaid2text: Python Scripts to export Plaid transactions and transform them into Ledger or Beancount syntax formatted files.

gnucash-to-beancount: A script from Henrique Bastos to convert a GNUcash SQLite database into an equivalent Beancount input file.

debanjum/gnucash-to-beancount: A fork of the above.

andrewStein/gnucash-to-beancount : A further fork from the above two, which fixes a lot of issues (see this thread).

hoostus/beancount-ynab : A converter from YNAB to Beancount.

hoostus/beancount-ynab5 : Same convert for YNAB from the same author, but for the more recent version 5.

ledger2beancount: A script to convert ledger files to beancount. It was developed by Stefano Zacchiroli and Martin Michlmayr.

smart_importer: A smart importer for beancount and fava, with intelligent suggestions for account names. By Johannes Harms.

beancount-export-patreon.js: JavaScript that will export your Patreon transactions so you can see details of exactly who you've been giving money to. By kanepyork@gmail.

alensiljak/pta-converters (Alen Šiljak): GnuCash -> Beancount converter (2019).

grostim/Beancount-myTools (Timothee Gros): Personal importer tools of the author for French banks.

Downloaders

bean-download (RedStreet): bean-download is a tool to conveniently download your transactions from supporting institutions. You configure it with a list of your institutions and arbitrary commands to download them, typically via ofxget. It downloads all of them in parallel, names them appropriately and puts them in the directory of your choice, from which you can then import. The tool is installed as a part of beancount-reds-importers. See accompanying article.

ofx-summarize (RedStreet): When building importers, it helps to be able to peek into a .ofx or a .qfx file that you are trying to import. The ofx-summarize command does just that. It ships with beancount-reds-importers, and should be available by simply invoking the command. Running the command on a file shows you a few transactions in the file. What is very useful is to be able to explore your .ofx file via the python debugger or interpreter.

Price Sources

hoostus/beancount-price-sources : A Morningstar price fetcher which aggregates multiple exchanges, including non-US ones.

andyjscott/beancount-financequote : Finance::Quote support for bean-price.

aamerabbas/beancount-coinmarketcap: Price fetcher for coinmarketcap (see post).

grostim/Beancount-myTools/.../iexcloud.py : Price fetcher for iexcloud by Timothee Gros.

xuhcc/beancount-cryptoassets (Kirill Goncharov): Price sources for cryptocurrencies.

xuhcc/beancount-ethereum-importer (Kirill Goncharov): Ethereum transaction importer for Beancount. Includes a script that downloads transactions from Etherscan and an importer for downloaded transactions.

xuhcc/beancount-exchangerates (Kirill Goncharov): Price source for http://exchangeratesapi.io.

tarioch/beancounttools (Patrick Ruckstuhl): Price sources and importers.

https://gitlab.com/chrisberkhout/pricehist (Chris Berkhout): A command-line tool that can fetch daily historical prices from multiple sources and output them in several formats. Supports some sources for CoinDesk, European Central Bank, Alpha Vantage, CoinMarketCap. The user can request a specific price type such as high, low, open, close or adjusted close. It can also be used through bean-price.

Development

Py3k type annotations: Yuchen Ying is implementing python3 type annotations for Beancount.

bryall/tree-sitter-beancount (Bryan Ryall): A tree-sitter parser for the beancount syntax.

jmgilman/beancount-stubs: Typing .pyi stubs for some of the Beancount source.

Documentation

Beancount Documentation (Kirill Goncharov): Official conversion of the Beancount documentation from Google Docs source to Markdown and HTML. This includes most of the Google Docs documents and is maintained in a Beancount org repo here by Kirill Goncharov.

Beancount Source Code Documentation (Dominik Aumayr): A Sphinx-generated source code documentation of the Beancount codebase. The code to produce this is located here.

SQL queries for Beancount (Dominik Aumayr): Example SQL queries.

Beancount —— 命令行复式簿记 (Zhuoyun Wei): A tutorial (blog post) in Chinese on how to use Beancount.

Managing my personal finances with Beancount (Alex Johnstone)

Counting beans—and more—with Beancount (LWN)

Interfaces / Web

fava: A web interface for Beancount (Dominik Aumayr, Jakob Schnitzer): Beancount comes with its own simple web front-end (“bean-web”) intended merely as a thin shell to invoke and display HTML versions of its reports. “Fava” is an alternative web application front-end with more & different features, intended initially as a playground and proof-of-concept to explore a newer, better design for presenting the contents of a Beancount file.

Fava Classy Portfolio (Vivek Gani): Classy Portfolio is an Extension for Fava, a web interface for the Beancount plaintext accounting software. The extension displays a list of different portfolios (e.g. 'taxable' vs. 'retirement'), with breakdowns using 'asset-class' and 'asset-subclass' metadata labels on commodities.

Fava Investor project (RedStreet): Fava_investor aims to be a comprehensive set of reports, analyses, and tools for investments, for Beancount and Fava. It is a collection of modules, with each module offering a Fava plugin, a Beancount library, and a Beancount based CLI (command line interface). Current modules include: Visual, tree structured asset allocation by class, asset allocation by account, tax loss harvester, cash drag analysis.

Fava Miler (RedStreet): Airline miles and rewards points: expiration and value reporting.

Fava Envelope (Brian Ryall): A beancount fava extension to add an envelope budgeting capability to fava and beancount. It is developed as a Fava plugin and CLI.

scauligi/refried (Sunjay Cauligi): An envelope budgeting plugin for Fava, inspired by YNAB: all expense accounts become individual budgeting categories, budgeting is carried out using transactions to these accounts, and the plugin automaticallyapplies a tag to all rebudget transactions so they can easily be filtered out. Provides budget and account views like YNAB.

BeanHub.io: A web front-end for Beancount content. "Since I started using Beancount, I have dreamed of making it fully automatic. For a few years now, I've been building tools for that goal. Connecting to the bank and fetching data directly from there is one of the goals I want to achieve. I built this feature and have been testing it for a while for my accounting book. Now my Beancount books are 80% fully automatic. I can open my repository, and the transactions from the bank will automatically appear as a new commit like this without me lifting a finger.

The whole import system is based on our open-source beanhub-import and beanhub-extract. The only proprietary part in the import flow is the Plaid integration. So, suppose you don't trust me and still want to import transactions automatically. As long as you connect to Plaid and write CSV files based on the transactions you fetched from Plaid, you should be able to have the same automatic transaction importing system without using the BeanHub service."

Blog posts:

https://beanhub.io/blog/2024/06/24/introduction-of-beanhub-connect/

https://beanhub.io/blog/2024/04/23/how-beanhub-works-part1-sandboxing/

https://beanhub.io/blog/2024/06/26/how-beanhub-works-part2-layer-based-git-repos/

jmgilman/bdantic: A package for extending beancount with pydantic. With this package you can convert your ledger to JSON, and more.

autobean/refactor (Archimedes Smith): Tooling to programmatically edit one's ledger, including formatting, sorting, refactoring, rearranging accounts, optimizing via plugins, migration from v2, inserting transactions in a ledger on import, and more.

seltzered/beancolage (Vivek Gani): An Eclipse Theia (vendor-agnostic vscode) app that tries to bundle existing beancount-based packages such as vscode-beancount and Fava.

aaronstacy.com/personal-finances-dashboard : HTML + D3.js visualization dashboard for Beancount data.

https://github.com/aleyoscar/beancount-pulsar : A Pulsar package for Beancount - Plain Text Accounting, with syntax highlighting, toggling comments, snippets for some directives and automatic indentation. Pulsar package: https://web.pulsar-edit.dev/packages/beancount-pulsar

Mobile/Phone Data Entry

Beancount Mobile App (Kirill Goncharov): A mobile data entry app for Beancount. (Currently only Android is supported.) Repo: https://github.com/xuhcc/beancount-mobile (Announcement).

http://costflow.io: Plain Text Accounting in WeChat. "Send a message to our bot in Telegram, Facebook Messenger, Whatsapp, LINE, WeChat, etc. Costflow will transform your message into Beancount / Ledger / hledger format transaction magically. Append the transaction to the file in your Dropbox / Google Drive. With the help of their apps, the file will be synced to your computer."