Tavis Ormandy

$Id: f0cc50a6fc6a5dd652c2b96ca9c1779f763fd6b1 $


One of my new years resolutions was to commit to using ledger – a commandline accounting tool. Ledger is a bit like Quicken, GnuCash or Mint, but for UNIX nerds.

Note: No relation to the cr*pto product with the same name.

It’s coming up to the end of the year, and this was one of the few resolutions I actually managed to keep!

I think you can probably accomplish everything ledger can do with other personal finance software. The reason you would choose ledger is that you’re sold on the efficiency and scriptability of the commandline, along with the grep, editor and revision control friendly file format.

If that sounds interesting, go take a look at the docs to learn more!

The TL;DR is that I’m hooked, and will keep using it.

Getting Started

It’s not easy to get started with ledger, and you’re probably going to have some uncommon financial arrangements that the documentation didn’t cover exactly. It could be anything, maybe something mundane like you split the utilities with a partner, but you’re the one who pays the bill?1

These things are easy to handle once you’re familiar with ledger concepts, but as nobody has the exact same arrangements as you, it’s not always a copy-and-paste situation.

This is where ledger’s flexibility can be a curse – the answer to questions like “How do I handle …?” tends to be “However you like!”. Cool, but you’re not going to have any opinions formed yet, so how do you know what you like?

I don’t really have a good solution – I think you just have to wing it until you’re proficient, then go back and fix any naive mistakes you made 🙈

Another problem is that you need a few months worth of data before you can fairly evaluate if you find it useful or not. That’s a big commitment to something that you’re not sure you’re actually going to enjoy!

After you’ve finally built up some data… your reward is having to learn the query syntax so you can actually do something useful with it… and that’s when you’ll realize you didn’t organize things optimally, and have to go back and edit the last few months of data! 😂

Now that I’ve scared everyone off, I can tell you I don’t regret that effort – ledger is great! You know that feeling when you find a solution that just feels “correct”? Well, ledger gives me that feeling.


So, what exactly does ledger look like? Well, there is no user interface, it’s a commandline tool to query your finances.

Note: If you want graphs, you pipe the output into gnuplot, like this. If you’re a stats nerd, you might prefer ledger-plots.

You can automatically import transactions from whatever format your bank provides, but I prefer to enter some transactions manually. I use vim’s colorcolumn feature to make margins and keep everything neatly aligned.

Once you’ve got importing and editing working smoothly, you can start answering questions about your finances.

$ ledger bal --period "this month" ^Expenses:
$ ledger reg --period "this year" --monthly ^Expenses:Auto:Gas
$ ledger bal --depth 1 --market ^Assets: ^Liabilities:
$ ledger bal --gain ^Assets:Brokerage
$ ledger bal --gain --limit 'commodity == "FOOBAR"' ^Assets:Brokerage
$ ledger bal --gain --limit 'commodity == "FOOBAR"' --limit 'lot_date(amount) < [365 days ago]' ^Assets:Brokerage
$ ledger bal --period "this june" ^Expenses: and @McDonalds
$ ledger reg --period "this year" --average --monthly --depth 1 ^Expenses:
$ ledger bal --period "last 12 months" --amount "amount / 12" --display 'top_amount(amount) > 20' ^Expenses:
$ ledger reg --period "this year" --subtotal --related ^Income:Reward
$ ledger reg --period "this year" %deductible

These are just some random examples, there are also budgeting and forecasting tools. It’s flexible enough that people use it for tracking billable hours, inventory and so on.

Naturally, it handles multiple currencies, arbitrary commodities, and you can track them as precisely (or coarsely) as you like.


This post is really just encouraging anyone considering getting started to take the leap if you were thinking about getting started in the new year!

  1. fyi, you could probably record that like this:

    ; Pay the power bill, John owes me half
    2023/10/1 * Power Company
       Expenses:Utilities:Power    $50
       Assets:Receivables:John     $50
       Assets:Checking            -$100
    ; John reimbursed me.
    2023/10/2 * John Doe  ; Flatmate
       Assets:Checking             $50
       Assets:Receivables:John    -$50

    …but maybe you want to record it like this:

    ; Pay the power bill, John owes me half
    2023/10/1 * Power Company
       Expenses:Utilities:Power    $100
       Assets:Checking             $100
    ; John reimbursed me his half.
    2023/10/2 * John Doe  ; Flatmate
       Assets:Checking             $50
       Expenses:Utilities:Power   -$50 ; [=2023/10/1]

    There is not always one right answer!↩︎