Finance under Control with Ledger (1) - Basics

Doing your finances on the commandline. Or more comfortably in Emacs with ledger mode.

Who of us does not know that. At the end of the money there is plenty of the month left, and is usually used by the Gasworks and the goldfish breeders' club to collect their annual fee (including the price increase) from your account.

I also had a time when I had to do a lot of financial juggling to live from month to month, even though I had as much money as today. I just did not have under control as well as I now have. The heart of the problem was actually that I almost never knew how much of the money in my account was really free to spend, and what bills would come up in the near future.

And then I sat down and decided to change that. First with pencil and paper, later with the support of the PC. I have tried various systems, bringing me finally to Ledger. Over the past year, I have been making little tests of how to handle my money, and since there were no major difficulties, I switched to Ledger at the beginning of 2019.

What can Ledger do (bookings & transactions)

Actually, ledger can do very few things, but for those it is very flexible, so it can cover a lot of use cases.

  1. It reads one or more text files with postings
  2. It sums up these postings (and distinguishes between the accounts in which they are posted)
  3. It either displays the complete register, or the balance on the screen

One thing that stands out is that Ledger definitely does not write to the postings in my files. I write my postings, and Ledger just evaluates them. It's very fast and precise in that.

An example:

2019-03-10 gas station
   Gasoline 50.00
   Checking account -50.00

What we see here is a transaction. This is the building block that we most often deal with in Ledger. It consists of the head, which indicates, when the transaction took place and who the partner was (here the gas station), as well as a number of postings (these are each a little indented). Postings are the smallest building block we use in Ledger. A posting identifies an account and an amount added to the account (or subtracted if the amount is negative). Several of these postings form a transaction.

The essential feature of a transaction is that the postings ALWAYS have to sum up to 0. Otherwise, the transaction is not valid and generates an error, crashing ledger.

Consequently, this means that there must be at least one counter entry in each transaction. A transaction thus always consists of at least two postings, and is therefore commonly called "double entry accounting". Every euro that comes from one account must go in another account.

If I let Ledger evaluate the above example and let me see the balance, it tells me, for example, that the account gas is now 50.00, and my checking account is now 50.00 in debt.


"That's great," you may say now, "if I need the 50.00 Euro again, then I'll just book it from the gasoline account, and …". But that's not how it works. The gas station will not like it if you took their money from them back. Even if you could do that in the theory of bookkeeping.

In reality, you use a few categories of accounts, that you then only use for certain types of postings. This is called the standard form (or chart) of accounts, and theoretically can be made by anyone as he feels like. In practice, however, a handful of chart of accounts have proven to be standardized in a way that different companies work with the same chart of accounts.

For me as a private user, a specific chart of accounts has been tried & tested that consists of 6 categories


Somewhere the money has to come from, and here we find all the accounts, where the money is almost "created". We remember: If my salary arrives on my checking account, it will need a corresponding conter entry. Therefore, the posting looks like this

2019-03-01 Company Baumeister
   Income:Salary -2000.00
   Credit:Bank 2000.00

As my bank account becomes more and more positive, the income are becoming more and more negative. Which also corresponds to the reality. When I get a salary, my company gets a little poorer.


The opposite is the case when I spend money

2019-03-10 gas station
   Expenses: Gasoline 50.00
   Credit:Bank -50.00

If I pay an invoice from my bank account, then the money has to "disappear" somewhere, and it does so only on "expenses" accounts.

In Ledger one speaks actually not of categories, but only of accounts. Accounts may also contain subaccounts (for example) Spending: Utilities: Gas and Spending: Utilities: Water. If I post something like these with these accounts:

2019-03-09 Stadtwerke
   Credit:checking  -100.00
   Expenses:Additional costs: Gas 50.00
   Expenses:Additional costs: Water 40.00
   Expenses:Additional costs: 10.00

Then you can see that here from the checking account an amount of 100 euros for the Stadtwerke was paid, which comes completely from the account Expenses:Additional costs. Of which 50.00 from the account for gas and 40.00 from the account for water. In addition, the Stadtwerke has charged me a general fee of 10.00, which I can not assign directly to the gas or water, but it is part of the additional costs. Here you can see that a transaction must contain at least two postings, but it may also be more. They must only add up to 0.


It's really easy. This includes all accounts on which there is usually money, ie the checking account, the savings account, the wallet. It's money (or values) that I have. If an account pays interest to me, it is most likely a credit account


These are debts I have somewhere. As a rule, I recognize debit accounts by paying interest because somebody has made money available to me here. Typically, these are the house loans or the credit card.


Compensation accounts are accounts that should not exist in a perfect accounting world. Unfortunately, the world is not perfect, and so I've got two subaccounts for compensations

  1. Compensations:debut

    I use this account exactly 1 time at the beginning of the bookkeeping, and then never again. If I start accounting sometime today, my checking account already has money and my credit card is in debt. So I book on my checking account the money that should be on it today, and the counter posting then goes against the account Compensation. Here, money is actually generated from very thin air. So, to not use this for cheating, I have exactly one posting at the very beginning, and then never again.

  2. Compensation:lostfound

    Since I also manage my cash (ie the wallet), it may sometimes happen that I simply have less money in the wallet than actually should be according to my bookkeeping. Sometimes I lose money in the washing machine, or elsewhere, sometimes money unexpectedly reappears in the lint filter. For all this there is this account as a counter account to the wallet. The account should be used as seldom as possible, and should be as little as possible off from 0. If this is no longer guaranteed, this is a sure sign of a general problem with discipline whith posting, or with spending cash. If I know, for example, that I have spent the night before 50.00 on a pub crawl, but I somehow 51.00 are missing in my wallet, then I just book 51.00 on the leisure account, and don't use thelostfond account for the missing 1.00. It is only used when I can no longer reasonably explain the disappearance.


Actually, Ledger has a built-in functionality that allows me to manage budgets (money that is reserved for certain expenses). Unfortunately, this is somewhat limited in terms of flexibility. So, using the Budget account and its subaccounts, I'm simulating a method that has worked well for my grandmother to put money aside for later: envelopes.

Whenever my salary arrives I put a little money into each of those envelopes. And then, when the car insurance wants its money, I open this envelope, and it contains exactly the amount that I have to pay as expected. Of course, I do not fill these envelopes literally. They do not even exist. They are just virtual envelopes, and the budget account is a subaccount of my checking account. The bank does not know this subaccount. From their perspective , I have 300 euros in my checking account. But Ledger can show me in this way that of these 300 euros are already 180 in a virtual envelope labeled car insurance, and I therefore have only 120 euros to spend.

The necessary postings of a budget transaction can sometimes be very confusing, but with a little practice this is possible. I will go into detail later.

Work easier

As mentioned earlier, Ledger simply reads the files and evaluates them. At no time does Ledger write anything in one of the files (there is a small exception that you have to explicitly request, and you almost never need)

But it also means that I have to type the complete postings myself by hand, including the matching counter postings. The account names must not contain any typos (which may be exciting for names such as Expenses:Household:Food:Biobox) If I call an account once dirtwater fee and once dirtwater charge, then these are for Ledger two completely different accounts, which then each individually summed up, and never merge

Ledger has some simplifications at hand for this very time-consuming and error-prone typing work:

The chart of accounts

Of course, I will eventually mistype an account name over time. And then, before I book money on any account called Expense:Carinsuracne and wonder why there's no change in the real account, it's better if Ledger controls it.

Ledger can be configured to tell it what accounts I want to use, and how the entire chart of accounts (all my accounts and subaccounts) is built. After that I can only use these accounts. Any typos will be mercilessly flagged, and Ledger will refuse to validate my postings until the error is resolved. Thankfully, he tells me exactly where the problem is.


An account named Expenses:Household:Groceries:Biobox can be very annoying to type. Therefore, Ledger offers the possibility to give short aliases instead of these word monsters. I then have to go e.g. Just type "Bio" and Ledger knows I mean that account.

The empty posting

Even amounts could be mistyped quickly, or you can't calculate in your head, what sum an counter posting has to have. If the Stadtwerke bills me I just want to write this:

2019-01-02 Stadtwerke
   Gas 12.34
   Water 56.78
   checking account

As you can see, there is no amount in the checking account, and if there is a transaction with exactly one account with no amount, Ledger simply takes the amount needed to balance the other postings. In this case, -69.12 will be posted to the checking account (ie 69.12 deducted)

The default account

Most of us have exactly one checking account, and all bank transactions run through this one account. Because even if you use something as alias as short as "Giro", it can be annoying to write it down for every transaction. However, Ledger offers the option to make an account have the function of an default account, which is then always accepted when the transaction is not cleared and the account is not already used in the transaction.

2019-01-02 Stadtwerke
   Gas 12.34
   Water 56.78

is therefore a valid posting record, if previously the checking account has been agreed as the standard account. In this case, the checking account is automatically taken as an counter account and the corresponding amount determined as explained in the section "empty posting"


2019-01-02 Stadtwerke
   Gas 12.34

is now a valid posting, even though the transaction violates the rule that a transaction must consist of at least 2 transactions. The missing posting goes to the previously defined default account

The Ledger Mode

As you can see, Ledger already has a lot of options built in that make typing easier. For the Emacs environment, there exists even a ledger mode, which further simplifies the input by e.g. proposing suitable posting data, or recurring postings after a few typed letters, or inserting them completely. In addition, it offers quite comfortable functions to create reports, or regularly adjusting the posted data with the reality. The Ledger Mode will be a article of its own.