Beancount: Lightweight FOSS Double-Entry Accounting...from the Command Line!

Apr 15, 2025 @ 7:00 am

Beancount is a neat FOSS project with a simple concept: full double-entry accounting from the command line.

Originally developed by Martin Blais, Beancount is a double-entry accounting system that stores your data in plain text, uses your favorite text editor, and integrates well with Unix-style workflows. No bloated GUI, no SaaS lock-in—just clean, transparent accounting with powerful reporting.

Now granted, I probably wouldn’t use it to manage General Motors’ finances…but in theory you could. All modern accounting is done using a system designed in the 15th century in Italy. It’s conceptually pretty simple. I’m not going to teach you bookkeeping here, but let’s take a look at this cool project.

Beancount Bullet Points

Beancount follows the philosophy of simplicity:

Plain text accounting: Your ledger is just a .beancount file, which is plain text.
Command-line native: Perfect for SSH servers, VPS environments, or your local terminal.
Auditable: Easy to track changes with version control systems like Git.
Flexible: Works for personal finance, small business bookkeeping, crypto, stock investments, and more.
Fast: Processes thousands of transactions quickly. Each operation is just an update to a text file.

Example Transaction

A simple transaction might look like this:

2025-04-05 * "Coffee at Local Cafe"
  Expenses:Food:Coffee  $4.50
  Assets:Cash

This records a $4.50 expense. In accounting language, you’re recording a debit from an asset (cash), and a credit to an expense (in this case, an expense account which is categorized/sub-categorized as Food, Coffee).

Every account is a simple text line, and you categorize as you go. Beancount also supports:

Multiple currencies
Commodity tracking (great for crypto)
Price declarations
Automated reporting
Balance assertions
Querying via its own powerful tool, bean-query

Quick Start with Beancount

Let’s get you up and running.

1. Install Beancount

If you’ve got Python 3, just run:

pip install beancount

Or clone from GitHub for the latest version:

git clone https://github.com/beancount/beancount.git
cd beancount
pip install .

2. Create Your First Ledger File

Make a file called example.beancount:

option "title" "My Personal Ledger"
option "operating_currency" "USD"

2025-04-05 open Assets:Bank:Checking USD
2025-04-05 open Expenses:Food USD

2025-04-05 * "Initial deposit"
  Assets:Bank:Checking  $1000.00
  Equity:Opening-Balances

2025-04-05 * "Groceries"
  Expenses:Food:Groceries  $120.00
  Assets:Bank:Checking

3. Check the Ledger

Run the Beancount checker:

bean-check example.beancount

No errors? You’re good to go!

4. Generate Reports

Beancount integrates with web interfaces like Fava:

pip install fava
fava example.beancount

This spins up a web dashboard for your ledger at http://localhost:5000.

5. Run Queries

You can run SQL-like queries on your data:

bean-query example.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"

Final Thoughts

Beancount is a simple idea, well-implemented. Because of its simple interface, you can easily script entries, and since the “database” is just a text file, it’s a cinch to edit or extend with your own tools and reports.

Now all we need is a WHMCS module…

raindog308

Dread Lord of LowEnd Content at LowEndBox

I'm raindog308, techno polymath and long-time LowEndTalk community Administrator. My technical interests include all things Unix, perl, python, golang, shell scripting, vintage operating systems such as MVS, and relational database systems such as Oracle, PostgreSQL, and MySQL.

I also enjoy using LEBs! I have an empire of little guys for VPNs, larger guys for apps, and big guys for databases and storage. When I'm not in front a screen I'm into German Shepherd dogs, quality knives, target shooting, theology, tabletop roleplaying games, and forest hiking.

I enjoy writing technical articles here on LowEndBox to help people get more out of their systems. You can find me on LowEndTalk @raindog308