Skip to content

Beancount and double-entry accounting

It is challenging to pick the right open source for your needs. Luckily, we have already picked one for you: Beancount. Beancount is a plain text accounting book software written in Python and published by Martin Blais in 2008. There are many benefits of using Beancount:

  • It's double-entry accounting, easy to track the movement of all money, and it's less error-prone
  • It's plain-text-based, and you can track changes with Git or another version control system.
  • It's very popular, with 3K GitHub repository stars
  • It has a very active community
  • There are many third-party tools in the ecosystem, such as Fava

First, let's look at plain text accounting. Proprietary accounting book software usually stores your accounting book in its database with its custom format. You can only read or write the accounting data using their user interface. Plain text accounting is very different, though. You write all your accounting entries in plain text, as the name suggests. For example, say you went out and purchased a burger at In-N-Out Burger for $5.00 with your cash as your lunch. You can then write a Beancount transaction in plain text like this:

2024-07-29 * "Buy burger as lunch"
    Assets:Cash            -5.00 USD
    Expense:Food            5.00 USD

The first column of the first line is a date. It records when the transaction happened. The following asterisk means this transaction is already confirmed instead of pending. The next column is narration. It describes what this transaction is about. The following two lines record the difference of each account. The first is negative USD 5, which goes to the Assets:Cash account. The second is USD 5, which goes to Expense:Food account.

Why do we want to record the same amount, USD 5, twice with opposite signs in different accounts? It seems redundant. Why not just one? If you only record the money amount change in one account, say Expense:Food, then it begs a critical question: where's the money coming from? To capture the fact that the money comes from our cash in pocket, i.e., Assets:Cash, we write down -5 USD in the cash account. As you can see, the sum of negative USD 5 and positive USD 5 is zero. Therefore, this transaction is balanced. Recording money changes in different accounts in the same transaction, and the total sum of all differences is always zero, is called double-entry accounting.

While it may seem redundant, the beauty of double-entry accounting is that not only does it allow you to track the flow of money, but redundancy also provides a way to ensure there's no error in the input. It takes more than one error in the same transaction to make it happen to be balanced. The benefits of double-entry accounting and its ability to track flow are not that obvious when dealing with simple transactions involving only two accounts and one currency. However, if you ever need to deal with complex transactions involving multiple accounts or currencies, you will see how powerful double-entry transactions are. We will show you later. For now, let's look at the basic concepts of double-entry accounting with Beancount.

Available accounts

An account in Beancount is the basic unit for tracking money movement and balance. You can think of it as a jar or piggybank for holding coins. You can move coins from one jar to another or vice versa. After you move coins, you can count how many coins are left in the jar to learn the balance. However, something different from an actual jar is that the balance amount in a Beancount account could be negative, which confuses many beginners. We will talk about it later.

There are a few basic types of accounts available in Beancount. As we saw in the previous example, Assets and Expenses are two of them. The complete list of accounts is shown here:

  • Assets - The assets you currently have, such as cash, savings in the bank, stock, real estate, or other commodities.
  • Income - The money or commodity you earn, such as salary, stock dividend, capital gains
  • Expenses - The money or commodity you spend, like your food spending, rent for a house or office, and office supplies.
  • Liabilities - The money or commodity you owe someone else, such as mortgage, credit card balance, student loan, or personal loan.
  • Equity - A holding place for anything else than the above-listed, such as open-account balances

The account name must start with one of the above basic account types and join with column symbols and sub-account names. For example, the following are valid account names:

  • Assets:Cash
  • Assets:US:Bank:Chase:Checking
  • Assets:US:Bank:Chase:Saving
  • Income:PiedPiper:Salary
  • Income:PiedPiper:RSU
  • Expenses:Food
  • Expenses:Travel
  • Expenses:Office:Rent
  • Liabilities:US:CreditCards:Chase:UnlimitedFreedom
  • Liabilities:US:PersonalLoan
  • Liabilities:US:Mortgage
  • Equity:OpeningBalances

The most confusing part for Beacount newcomers is definitely the fact that the Income amount is usually negative. Say you mow the lawn for your neighborhood and earn 50 bucks. You can write a transaction like this:

2024-07-29 * "Mow the lawn for neighborhood"
    Income:MowingLawn       -50.00 USD
    Assets:Cash              50.00 USD

The next day, you find ten bucks on the sidewalk when you are jogging, and you pick it up. Here, you can write a transaction like this:

2024-07-30 * "Found money on the sidewalk"
    Income:Windfall         -10.00 USD
    Assets:Cash              10.00 USD

At this moment, here's the summary of the balance of each account:

Account Balance
Assets:Cash 60.00 USD
Income:MowingLawn -50.00 USD
Income:Windfall -10.00 USD
Income -60.00 USD

Because Income:MowingLawn and Income:Windfall are sub-accounts of Income, you need to combine all the sub-accounts when summarizing Income. Thus, the total Income would be -60 USD.

Your income is negative 60 USD. That sounds very strange. We indeed earned some money, so why is our income negative? The beauty of a double-entry accounting system is that it tracks the flow of all money movements. When you gain cash as your assets, it must be taken out somewhere else to make it a balance. Therefore, think about income as something you got from someone else in exchange for your labor or something you harvest from the mother of nature with value.

For example, you spend one hour digging in a gold mine and find one ounce of gold. Surely, you have one ounce of gold as your assets, but to the mother of nature, there's one ounce of gold less. The mother of nature is your income source. To her, that's a negative one ounce of gold. Think of it like digging a hole in the ground. If you see soil dug out as your asset, the hole in the ground would be your income. The volume of the hole you dug and the pile of dirt should be the same.

Income is usually negative because it's like digging a hole in the ground.
Income is usually negative because it's like digging a hole in the ground.

That is beautiful because many things are balanced, as in our world of physics. The law of conservation of mass states:

For any system closed to all transfers of matter and energy, the mass of the system must remain constant over time, as the system's mass cannot change, so the quantity can neither be added nor be removed. Therefore, the quantity of mass is conserved over time

Similarly, for energy, the law of conservation of energy states:

The total energy of an isolated system remains constant; it is said to be conserved over time. In the case of a closed system the principle says that the total amount of energy within the system can only be changed through energy entering or leaving the system. Energy can neither be created nor destroyed; rather, it can only be transformed or transferred from one form to another.

After understanding that, you would see that anything that has value won't appear in thin air; there must be something in exchange for it, and everything is balanced, just like nature. A double-entry accounting system perfectly captures this principle. Therefore, it would be natural to use it as long as you understand this principle. Congratulations! You just learned the most challenging concept of why income is negative in Beancount. This is the first step in your journal learning the zen of balance.