Understanding the foundational principles of Beancount is essential for effective personal finance management. This post delves into the core concepts that underpin Beancount’s plain-text double-entry accounting system. You’ll explore how every transaction must be balanced, the five fundamental account types (Assets, Liabilities, Equity, Income, Expenses), and the role of commodities in tracking various assets. Additionally, the article introduces key financial statements like the balance sheet and income statement, illustrating how Beancount provides a clear and structured view of your financial health. Whether you’re new to Beancount or seeking to solidify your understanding, this guide offers a comprehensive overview of its conceptual framework.

Each Transaction is Balanced

Beancount is built on double-entry accounting, a system that ensures every transaction is balanced.

For every change in one account, there must be an equal and opposite change in another.

Example:

1
2
3

2023-04-01 * "Bookstore" "Bought a novel"
    Assets:Bank:Checking  -25.00 USD
    Expenses:Books 25.00 USD

The above transaction represents we spend 25 USD dollars from our bank account to buy a novel book.

Here, money leaves your bank account and increases your expenses.

Beancount automatically checks that all entries balance — no math errors, ever. This is enforced by the Beancount. Imbalanced transactions are NOT allowed in Beancount.

Here is a very good introduction of double-entry counting method, written by the author of Beancount - Martin Blais.

Accounts

As mentioned in Beancount Basics, in Beancount, there are five fundamental account types: Assets, Liabilities, Income, Expenses and Equity. The relation between these account types can be visualized in the following picture:

Income and Expenses accounts control the “input” and “output” of your ledger. The balance change in these accounts matters over a time. For example, we can ask “how much I spend on the restaurants last month?” or “how much I earned last year?” Income accounts usually have negative balance while Expenses accounts usually have positive balance.

On the contrary, Assets and Liabilities accounts represent something that you owned and owed. The balance of these accounts at a particular point in time is something that we are interested in. For example, we can ask: “How much money I have in my Chase checking account?” or “how much is my remaining mortgage principle?” Assets accounts have positive balance and Liabilities have negative balance.

The last account type is Equity. It is used for accounts that hold a summary of the net income implied by all the past activity. Basically, it is used to make the following equation always true:

$$ \text{Assets} = \text{Liabilities} + \text{Equity} $$

The Equity account type holds the total net worth. In the most cases, we will not use this Equity account. Beancount handles it automatically for us.

The following table summarize all these five account types.

In Beancount, all the accounts must be defined under these five account types. There is NO EXCEPTIONS.

Commodities

In Beancount, a commodity represents any item of value that can be tracked within your financial records. This includes traditional currencies like USD or EUR, as well as stocks, cryptocurrencies, precious metals, or even non-financial items such as air miles or hours worked. Commodities are typically denoted by uppercase symbols (e.g., USD, AAPL, BTC, AIRMILES).

In the example below, we define a commodity named APPL to track the number of Apple company stock shares:

1

2025-01-01 commodity AAPL

Then, we can log the transaction:

1
2
3

2025-03-15 * "Bought shares of AAPL"
  Assets:Investments:Brokerage  10 AAPL {150.00 USD}
  Assets:Bank:Checking         -1500.00 USD

In this context, USD represents another commodity, commonly denoting US dollars in accordance with standard conventions.

This transaction means we buy 10 share of Apple stock with the cost of 150 US dollars per share. More about how to log the stock investing will be discussed in another post. The point of this example here is to show that we can define any commodity in Beancount to fit our requirements.

Balance Statement

Beancount, a balance statement is a financial statement that provides a snapshot of your financial position at a specific point in time. It details your assets, liabilities, and equity.

The above is an example of balance statement shown by the Fava. Usually, the Assets are listed on the left and Liabilities and Equity accounts are list on the right.

By regularly generating and reviewing balance sheets, you can maintain a clear understanding of your financial health and make informed decisions based on your assets, liabilities, and equity.

Income Statement

In Beancount, an income statement, also known as a profit and loss statement, is a financial report that summarizes your revenues (income) and expenses over a specific period. This statement helps assess your financial performance by calculating the net income, which is the difference between total income and total expenses.

The income statement produced by Beancount typically includes:

• Income Accounts: Displays the total amounts earned from various sources. The numbers are usually negative.
• Expense Accounts: Shows the total amounts spent in different categories. The numbers are usually positive.
• Net Income: Calculated as total income plus total expenses. A negative net income indicates a profit, while a positive net income indicates a loss.

By effectively generating and analyzing income statements in Beancount, you can gain valuable insights into your financial performance, aiding in better financial planning and decision-making.