hledger
plain text accounting software
I discovered hledger last week and I hope it's not too early to describe it as life-changing. thank you for building this software --gnidan
I have massively enjoyed using hledger and am incredibly impressed with how active the development and support for it are! --Pixelized
I completed my first year of bookkeeping for both business and personal expenses with hledger last year. I can honestly say that I observed zero bugs with the software. It has worked seamlessly. --csgagnon
I've been using hledger for managing my personal finances for a few years now, and I'm really happy with it! --guivho
hledger focuses on testing and correctness alongside comprehensive documentation, giving me a much better picture of its capabilities. I dove in and spent a week entering a year and a half of data, which was enough to convince me. hledger is truly an amazing tool. I can’t count how many times I’ve thought wouldn’t it be nice if… only to realize it can already do that ... The attention to detail is marvelous. --Shiv J. M.
hledger is...
- free GPLv3+ accounting software that runs on unix, mac, windows, and the web
- based on readable, version-controllable, future-proof plain text files
- the most user friendly plain text accounting app
- interoperable with Ledger, Beancount, Fava, Paisa, ...
- fast, lightweight, and dependable (we pay $50 for regression reports/fixes)
- local, not cloud-based (your private financial data remains under your control)
- free from vendor lock-in
- shipped with command line, terminal, and web UIs
- good at importing CSV from banks and other financial institutions
- good for tracking money, investments, time, or any countable commodity
- good for learning more about double entry bookkeeping
- comfortable for technical users, also usable by non-techies (command line skills are useful but not essential)
- automatable and scripting-friendly
- built with the powerful, high assurance Haskell language
- actively used, developed and supported by Simon Michael and contributors since 2007
- strengthened by community feedback and funding
More about Features.
Welcome! Don't hesitate to ask questions. Or explore the documentation links in the sidebar (if not visible, click/tap the icon at top left).
Quick start
This plain text accounting stuff is both useful and more fun than it sounds - care to give it a try ? See Get Started, or the following short guide:
1. Install hledger
Install hledger on your computer. The Install page shows how to get an up-to-date version quickly.
2. Record transactions
hledger reads transactions from a journal file.
By default this is ~/.hledger.journal or C:\Users\USER\.hledger.journal.
You can change this by configuring $LEDGER_FILE.
This file uses journal format, containing transaction entries like this (the black text):
A transaction entry begins with a date and description, followed by an indented list of accounts and amounts. Note the 2 or more spaces required between each account name and amount. A positive amount means "added to this account", a negative amount means "removed from this account" (AKA debit and credit). The amounts in a transaction must add up to zero. If you leave one amount blank, it will be calculated automatically.
Here's an example journal, with comments. Transactions are ordered by date, and the first one sets starting balances.
2023-01-01 opening balances ; <- First transaction sets starting balances.
assets:bank:checking $1000 ; <- Account names can be anything.
assets:bank:savings $2000 ; <- Colons indicate subaccounts.
assets:cash $100 ; <- 2+ spaces are required before the amount.
liabilities:credit card $-50 ; <- A debt; these are negative.
equity:opening/closing $-3050 ; <- Starting balances come from equity.
; Equity is also usually negative.
; (Reports can show as positive when needed.)
2023-02-01 GOODWORKS CORP ; <- Date order is recommended but optional.
assets:bank:checking $1000
income:salary ; <- $-1000 is inferred here to balance the txn.
; Income amounts are negative.
2023-02-15 market
expenses:food $50
assets:cash ; <- $-50 is inferred here.
Save this as your journal file, using a text editor.
Or, you could run hledger add or hledger web and record these transactions interactively. (No need to enter the comments.)
3. Add declarations (optional)
Account types
In accounting there are five standard account types: assets, liabilities, equity, revenues (or income), and expenses. hledger also uses a couple of subtypes: cash, conversion.
It's recommended to declare the types of your top level accounts,
to help reports show the right accounts.
hledger can infer types from english account names, but you may be using another language,
and anyway it's good practice to make this explicit.
So add account directives at the top of your journal file, something like these:
; Top level account types. Subaccounts will inherit these.
account assets ; type:A
account assets:bank ; type:C
account assets:cash ; type:C
account liabilities ; type:L
account equity ; type:E
account equity:conversion ; type:V
account revenues ; type:R
account expenses ; type:X
Translations: ar da de en es fr ja ko no pt se zh
Account and commodity names
If you want more error checking, you can declare all allowed account names (not just top level accounts), and all allowed commodities/currencies, and then use strict mode, which disallows any others:
; All accounts.
account assets ; type:A
account assets:bank ; type:C
account assets:bank:checking
account assets:bank:savings
account assets:cash ; type:C
account liabilities ; type:L
account liabilities:credit card
account equity ; type:E
account equity:conversion ; type:V
account equity:opening/closing
account income ; type:R
account income:salary
account income:gifts
account expenses ; type:X
account expenses:rent
account expenses:food
account expenses:gifts
; Currencies, and their numeric display style.
commodity $1000.00
$ hledger check --strict
$ hledger -s CMD ...
Declaring accounts also sets their preferred display order (instead of sorting alphabetically).
4. Run reports
Now you can see reports, such as...
A list of accounts, showing the hierarchy and types detected:
$ hledger accounts --tree --types
assets ; type: A
bank ; type: C
checking ; type: C
savings ; type: C
cash ; type: C
liabilities ; type: L
credit card ; type: L
equity ; type: E
conversion ; type: V
opening/closing ; type: E
income ; type: R
salary ; type: R
gifts ; type: R
expenses ; type: X
rent ; type: X
food ; type: X
gifts ; type: X
A balance sheet, showing what you own and owe:
$ hledger bs
Balance Sheet 2023-02-15
|| 2023-02-15
=========================++============
Assets ||
-------------------------++------------
assets:bank:checking || $2000
assets:bank:savings || $2000
assets:cash || $50
-------------------------++------------
|| $4050
=========================++============
Liabilities ||
-------------------------++------------
liabilities:credit card || $50
-------------------------++------------
|| $50
=========================++============
Net: || $4000
An income statement (AKA profit and loss report), showing what you received and spent:
$ hledger is -MTA
Income Statement 2023-01-01..2023-02-28
|| Jan Feb Total Average
===============++==============================
Revenues ||
---------------++------------------------------
income:salary || 0 $1000 $1000 $500
---------------++------------------------------
|| 0 $1000 $1000 $500
===============++==============================
Expenses ||
---------------++------------------------------
expenses:food || 0 $50 $50 $25
---------------++------------------------------
|| 0 $50 $50 $25
===============++==============================
Net: || 0 $950 $950 $475
An account register, showing the transactions and running balance in a particular account:
$ hledger aregister checking
Transactions in assets:bank:checking and subaccounts:
2023-01-01 opening balances as:ba:savings, as:.. $1000 $1000
2023-02-01 GOODWORKS CORP in:salary $1000 $2000
Next steps
Congratulations, you can now use hledger to track your daily finances! But see Get Started for more detailed help and tutorials.
If you are new to bookkeeping, accounting, or plain text accounting: these are valuable skills, and they do take some time to master. With practice, more doc reading, and support/discussion, you will gradually
- build up a set of account names best suited to you
- learn the proper journal entries for your real-world transactions
- learn how to produce the reports most useful for you
- and learn new workflows that you may find more convenient.
Other user interfaces
Instead of using the command line, you can use the ui or web interfaces
(or repl, add, iadd, ...)
Time tracking
hledger can also read time logs, in timeclock format:
i 2023/03/27 09:00:00 projects:a
o 2023/03/27 17:00:34
i 2023/03/31 22:21:45 personal:reading:online
o 2023/04/01 02:00:34
$ hledger -f 2023.timeclock register -D
2023-03-27 projects:a 8.01h 8.01h
2023-03-31 personal:reading:online 1.64h 9.65h
2023-04-01 personal:reading:online 2.01h 11.66h
or in timedot format:
2023/2/1
biz:research .... ..
fos:hledger .... .... ....
2023/2/2
fos:ledger .
fos:haskell ..
biz:client1 .... ....
$ hledger -f 2023.timedot balance -tDTA # tree, Daily, Total, Average
Balance changes in 2023-02-01..2023-02-02:
|| 2023-02-01 2023-02-02 Total Average
============++==========================================
biz || 1.50 2.00 3.50 1.75
client1 || 0 2.00 2.00 1.00
research || 1.50 0 1.50 0.75
fos || 3.00 0.75 3.75 1.88
haskell || 0 0.50 0.50 0.25
hledger || 3.00 0 3.00 1.50
ledger || 0 0.25 0.25 0.12
------------++------------------------------------------
|| 4.50 2.75 7.25 3.62
CSV import
Most banks and financial institutions provide data in CSV format. hledger can read from any CSV (or SSV, TSV, or other character-separated) file representing transactions. Eg:
"Date","Notes","Amount"
"2023/2/22","DEPOSIT","50.00"
"2023/2/23","TRANSFER TO SAVINGS","-10.00"
# bank.csv.rules # this rules file tells hledger how to read bank.csv
skip 1
fields date, description, amount
currency $
account1 assets:bank:checking
if WHOLE FOODS
account2 expenses:food
if (TO|FROM) SAVINGS
account2 assets:bank:savings
$ hledger -f bank.csv print
2023-02-22 DEPOSIT
assets:bank:checking $50.00
income:unknown $-50.00
2023-02-23 TRANSFER TO SAVINGS
assets:bank:checking $-10.00
assets:bank:savings $10.00
The import command detects just the new transactions, and adds them to the journal:
$ hledger import bank.csv
imported 2 new transactions from bank.csv
$ hledger import bank.csv
no new transactions found in bank.csv
$ hledger aregister checking
2023-01-01 opening balances as:ba:savings, as:.. $1000.00 $1000.00
2023-02-01 GOODWORKS CORP in:salary $1000.00 $2000.00
2023-02-22 DEPOSIT in:unknown $50.00 $2050.00
2023-02-23 TRANSFER TO SAVINGS as:ba:savings $-10.00 $2040.00
More: Tutorial: Import CSV data
More examples...
- Charts and Graphs
- HTML reports
- Interop with other software
- Investing and trading
- Mobile apps
- Scripts and Scripting
- Workflows
- The hledger Cookbook
- The PTA Cookbook
Site tips
- Use the horizontal lines icon at top left to toggle the sidebar.
- Use the paintbrush icon to change theme.
- Use the magnifying-glass icon to search.
- Access keys are also available:
stoggle sidebar,ttheme,/search,
1home page,2recent changes,<previous page,>next page.