Lazy Beancount

An opinionated guide on how to start (and continue) tracking personal finances using the open-source Beancount accounting system. Packaged in Docker with batteries included.

Features¶

The main 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 so you don't have to build/configure everything from scratch.

The flow unique to this guide is visual spreadsheet-like balance management via beantab. It allows you to easily enter strict and flexible ("fix later") balance checks and then observe the discrepancies visually (and later add transactions to remove these). At the same time, your account and net worth graphs will be the first thing you can rely upon.

Who this is for¶

Anyone who wants a better understanding of various aspects of their financial life. Maybe you want to see your spending patterns and optimize something. Or maybe you want to track your FIRE goals. This set of tools will be especially useful if you have multiple accounts, savings and/or investments, want to track cash spending, and also if you want to optimise tax-related things. You can get an idea of the existing functionality at the Functionality page. Where the feature does not exist yet, Beancount excels in flexibility and extensibility.

If your things are simple enough, you can always use spreadsheets or one of the alternative tools. But with Beancount you can track almost anything finance-related and there is existing code for a lot of use-cases. In my opinion, it's the best product in the (open source ✖ available features ✖ hackability) niche.

Finally, if you were already interested in plain-text accounting premises but lazy enough not to bother tracking all transactions manually or setting up Beancount from scratch and testing all the libraries, or both. If you want to get Fava in Docker or Podman and avoid the hassle of setting up Python, pip, etc on your platform (but still want to have your data kept private), this may be the easiest Beancount tutorial to follow.

This system may appear complicated on the first glance. You will still have to learn how plain text accounting and Beancount in particular works. There may be some technical details to learn. In exchange you receive a lot of flexibility and ability to do whatever you want to do with your financial data (especially if you prefer Python coding over spreadsheet management: it is not required for most of the already provided functionality).

Everything is configurable via Beancount files, YAML files (introduced in Lazy Beancount) and some additional UIs. Being comfortable working with command line, structured text files and version control system (e.g. git) will be an advantage. Some amount of coding (in Python) will be helpful if you want to extend the framework.

Why this guide exists¶

At some point I started using spreadsheets to track basic personal financial data. For some time I also have been considering finding or implementing the system for tracking investments and calculating taxes. In the process I've been researching various available open source options. After briefly trying few ones and noting available functionality I chose Beancount. Throughout the first year I moved pretty much all of my tracking to Beancount, and it turned out to be even more flexible and feature-rich than I expected.

Multiple sources mention the learning curve as steep and, indeed, Beancount seems harder to start with than some other systems that are fully UI-based and don't get into accounting concepts and terminology too much. However, I found my own path to Beancount pretty satisfactory and decided that this experience is worth describing to make the entry easier. While it started as a guide, it evolved into a maintained GitHub repository together with a Docker image and later expanded to additional Fava extensions that can be used separately and modularly.

Some of the approaches I took are, probably, unconventional, and for various reasons may go against the recommendations from the original docs. Hence, the guide is referred to as "opinionated". You don't have to do all the things the same way and some of the ideas may still turn out to be useful for you.

Links to useful libraries and resources for Beancount are sometimes scattered and sometimes outdated. You can follow Beancount contributions doc, awesome-beancount or mailing list to keep up-to-date. This guide is an attempt to gather the best and tested resources and bootstrap an overall Beancount experience.

How to use it¶

The guide is designed to be followed step-by-step like a tutorial and is broken down into "stages". You can start with Setup for installation instructions and high-level recommendations, then go through the Stage I to have something working and useful by the end of it. You can follow through the rest of the stages at your own pace, or whenever you need the functionality mentioned.

Or you can just use this site as a reference to useful resources and tips if you already use Beancount in a different way or if you prefer to develop your own approach. In case you have an existing setup, of course you can build on top of it.

Questions or feedback?¶

Please leave feedback to support project development.