Frequently Asked Questions

If you have additions or suggestions, just click the "edit this page" link at the bottom, or let us know in the chat.

ACCOUNTING

What's accounting ?

Accounting means keeping track of the flow and whereabouts of things you value, such as money or time, and using this information for insight, planning and decision-making. Here's hledger's Accounting concepts page and Accounting links.

Why might I want to do accounting ?

For clarity, control, planning, accountability, compliance, tax reporting, tax audits. It clarifies activity, priorities, obligations, opportunities.

What's double-entry accounting ?

Double-entry bookkeeping is the traditional method for keeping accounting records reliably. For every movement of value (a transaction), both the source and destination are recorded. These are labelled "Credit" and "Debit", to minimise working with negative numbers. Simple arithmetic invariants help prevent errors.

What's plain text accounting ?

You can read more about Plain Text Accounting (PTA) at https://plaintextaccounting.org. In short, it is a way of doing Double Entry Bookkeeping (DEB) and accounting on a computer, using simple text files and small flexible tools, rather than databases and big applications. Minus and plus signs are usually used instead of Credit and Debit notation, making it easier to learn than traditional DEB. The text files are human-readable and easy to convert or to manage with version-control tools.

THE HLEDGER PROJECT

What's hledger ?

One of the best tools for doing Plain Text Accounting. It's free and you can read all about it at the https://hledger.org home page.

Why was hledger created ?

I needed to make working on finances (and financial tools) more fun for myself. Ledger was incomplete and stalled, using/supporting/community-building around it was frustrating, and I wanted to work with Haskell not C++. My goals included:

  • Provide a more usable, robust, documented, cross-platform-installable version of Ledger.
  • Provide a more maintainable and hackable version of Ledger for developers.
  • Provide a useful library and toolbox for finance-minded Haskell programmers.
  • Explore the suitability of Haskell for such applications.
  • Attempt to build a successful, solvent, self-supporting project in a thriving ecosystem of financial software projects.

See also: hledger and Ledger: History.

What is the hledger project's current mission and plans ?

  1. Help make plain text accounting more usable and useful for all.
  2. Bring relief to people experiencing financial and financial technology stress, by providing dependable, empowering accounting tools, learning materials, and community.
  3. Help people and communities in all countries increase their financial mastery and freedom.
  4. Help grow a shared global culture of accountability and sustainability.
  5. Starting with this project and ourselves.

Here is the ROADMAP.

HLEDGER AND PLAIN TEXT ACCOUNTING

We use another system, we don't need this ?

Every tool has strengths and weaknesses. hledger is lightweight, flexible and relatively easy to glue into other systems; it might be worth exploring as a complementary tool.

How do you collaborate with accountants and the non-PTA world ?

Depending on their needs, you send them a few standard reports (balance sheet, income statement, itemized account registers or a full transaction journal)

  • as plain text (optionally spruced up with your own templates)
  • or as HTML
  • or as PDF
  • or as CSV they can import into Excel and elsewhere

Must I enter data in a text editor ??

No. A good text editor can be a very efficient way to work on your data, but there are other ways:

  • use a terminal-based data entry tool like hledger add or hledger-iadd
  • use a web-based data entry tool like hledger-web
  • use a phone-based data entry app like MoLe
  • import CSV data, avoiding manual data entry.

What is a good set of account names to start with ?

The chart of accounts (list or tree of account names) will vary according to your language and your accounting situation, and will usually evolve as your needs change. Currently hledger does not have any built-in default chart of accounts. You can start small: name just the accounts you need, as you need them. Or, copy a chart of accounts that seems suitable, from other accounting software or from the web. Some examples can be found at https://plaintextaccounting.org/Choosing-accounts.

What can hledger do for me ?

hledger can provide clarity and insight into your personal or business finances, time logs, or other dated quantitative data, with relatively little effort on your part. You need only provide a list of transactions, as a plain text file in a simple human-readable format. (Or a CSV file plus some conversion rules.) From this hledger can generate a variety of useful reports and interactive views. See Features.

How could that help me ?

  • More clarity, transparency and accountability, for yourself or others
  • Know what you owe, or who owes you
  • Know where the money went; steer your spending
  • Know how you spent your time; easy client invoicing
  • More foresight and ability to plan; avoid overdrafts, late fees, cashflow crunches
  • Know all the numbers you need for tax reporting; know how much to save for estimated taxes
  • Less stress, fear or overwhelm
  • More satisfaction, empowerment, and prosperity!

Isn't manual data entry a pain ?

  • Not if you spend a few minutes every day.
  • Not if the benefits are worth it to you.
  • Not if you use a comfortable editor and copy/paste a lot.
  • Not if you use tools to help (editor modes, hledger add, hledger-iadd, hledger-web..)
  • Not if you use rules to generate your recurring transactions.

Isn't importing from banks a pain ?

Not once you have set up a manual or automated routine for it. The possibilities for automation vary by bank and country, but the following semi-manual workflow is almost always possible and quick:

  1. Manually download recent CSVs from your bank's website
  2. hledger import ACCT1.csv ACCT2.csv ...
  3. review/clean up the new entries in your journal.

Isn't plain text ugly and hard to use ?

No way, it's great, honest. We love it. You'll love it. It's fast. It's cheap. It's non-distracting. It keeps you focussed on the content. It's copy-pasteable. It's accessible to screen readers. It's resizable. You can pick the font and colours. You do not need "Plaintext Reader, Trial Version" to read it. you do not need "Plaintext Studio Pro" to write it. You can use your favorite editor and skills you already have. You can search in it! You can version control it. It works well over remote/slow connections. It's future-proof. It will be just as usable in 15 or 50 years. You can still read it even without the right software or (if you print it) a working computer. "Accounting data is valuable; we want to know that it will be accessible for ever - even without software. We want to know when it changes, and revision-control it. We want to search and manipulate it efficiently. So, we store it as human-readable plain text."

Isn't this too weird for my family, business partners, tax accountant to use ?

Maybe. You can ask them to enter data via hledger-web, or import from their mobile expenses app or a shared spreadsheet. You can show them the hledger-web UI, or HTML reports, or give them CSV to open in a spreadsheet.

Why are my revenue (income), liability, and equity balances negative ?

It's normal; it's because hledger and most other plain text accounting tools use negative and positive numbers instead of credit and debit terminology. Certain hledger reports (balancesheet, incomestatement, cashflow) and flags (--invert) can show them as positive when needed. See Accounting > Debits and credits.

HLEDGER AND OTHER SOFTWARE

How does hledger relate to Ledger ?

hledger (begun 2006) is inspired by, and a friendly coopetitor of, John Wiegley's Ledger (begun 2003). It is an attempt to rewrite Ledger in a more expressive programming language and take it to the next level in usability and practicality. See hledger and Ledger.

What is/was ledger4 ?

hledger has its own parser for a file format close to Ledger's. In 2012 John Wiegley prototyped a more exact conversion of Ledger 3's parser to Haskell, calling it ledger4. For a while I integrated this as an alternate file format within hledger, hoping to improve our ability to read original Ledger files, but the parser needed lots more work to become useful, so later I removed it again.

How is hledger different from / interoperable with... ?

See Cookbook > Other software for notes on Ledger, Beancount, GnuCash, Quickbooks, etc. Also:

How could I import/migrate from...

How could I export/migrate to...

GETTING STARTED

There are so many docs, where do I even.. ?

You're right. You can skip them: just run hledger for help.

When you'd like a bit more guidance, use the Get Started page, and/or the chat room.

If you want the most complete reference, use the hledger manual. If you read this and nothing else, you'll be a hledger expert. But it is rather large; so maybe read the table of contents, the first sections, and just skim the rest so you know where to find out more.

You can jump to topics in the manual with a url like hledger.org/hledger#time-periods. (This makes a good web browser keyword; eg in your browser, define hm TOPIC as a shortcut for https://hledger.org/hledger#TOPIC.) The website also has a search feature. To read a local copy of the manual, see hledger help -h.

Where can I find non-english docs ?

Unfortunately, I know of very few non-english docs for hledger. There must be some I don't know about, please contribute any good links.

Could you help translate some docs ? Please get in touch.

Otherwise, you could try Google Translate or similar.

There are couple of non-english videos at PTA: Videos and hledger: Videos.

How do I set the default file to something other than ~/.hledger.journal ?

See hledger manual: Setting LEDGER_FILE.

How should I organise files ?

See PTA FAQ: How should I organise files ?.

What account names should I use ?

See PTA FAQ: How should I choose account names ?.

JOURNALS

How can I tidy a journal file ?

Method 1: use Emacs's ledger-mode. This is the least destructive way, but it requires Emacs and ledger-mode. Select the whole journal, or a region, or move the cursor to a specific transaction, and press M-q.

Method 2: use hledger's print command. You might need to work around some current limitations:

  • Only transactions are printed, not directives or inter-transaction comments. Workaround: group directives at the start of the file, and copy them to the new output, and don't use inter-transaction comments.

  • Transactions will be printed in date order. Workaround if you don't want to sort them all by date: tidy just a subset of transactions at a time (using -I if needed). Eg in Emacs: select region, C-u M-S-| hledger -If- print.

  • If you have include directives, the included files' transactions will also be printed. Workaround: tidy one file at a time, temporarily commenting out include directives.

  • Amounts will be right-aligned, within each transaction but not across all transactions. Workaround if you want whole-file alignment and more alignment options, like aligning on decimal mark: use ledger-mode.

The print method has some inconveniences, but also extra power, eg to select a subset of transactions with a query, or to transform the data with --explicit, --infer-costs, --alias, --commodity-style, --pivot, etc.

Some examples:

cp $LEDGER_FILE $LEDGER_FILE.bak
hledger print > $LEDGER_FILE.new && mv $LEDGER_FILE.new $LEDGER_FILE

Using the sponge helper for updating a file in place:

hledger print | sponge $LEDGER_FILE

Preserving directives and inter-transaction comments (though not their positions):

(grep -E '^([#;]|[[:alpha:]])' $LEDGER_FILE; hledger print) > $LEDGER_FILE.new

Note, any time you do mass edits to valuable data, it's wise to keep a backup and check your changes. Eg by comparing reports before and after, by running your usual hledger checks, or by using a version control system.

Why does this entry give a "no amount" error even though I wrote an amount ?

2019-01-01
  a $1
  b

Because there's only a single space between a and 1, so this is parsed as an account named "a 1", with no amount. There must be at least two spaces between account name and amount.

Why does this journal fail strict account checking even though I declared all accounts ?

account assets:bank:checking ; my bank account
account equity               ; equity

2023-01-01
    equity
    assets:bank:checking   $1000

Because there's only a single space between assets:bank:checking and the ; comment, so the comment is parsed as part of the account name. (hledger accounts shows this.) There must be at least two spaces between an account name and anything that follows it.

Why do some directives not affect other files ? Why can't I include account aliases from a sub file ?

Directives vary in their scope, ie which journal entries and which input files they affect. The differences are partly due to historical accident, and partly by design, so that reordering files, or adding another file, does not change their meaning. See journal format > Directives and multiple files. Related discussion: #217, #510, #1007.

Can I use arithmetic expressions in journal entries ?

Eg, Ledger-style amount expressions ? Generally no, hledger doesn't allow this. (If you want it, you could revive PR #934.)

In some cases, you can emulate it with auto postings, which can multiple amounts by a constant. Eg to (effectively) divide all food expenses by 2, you could add this rule, and enable it with --auto:

## Add a posting subtracting half from every food expense (good enough for expense reports)
= revenues
    (expenses:food)  *-.5

Related: 50% of the balance?

How could I record call/put stock options ?

Here's a suggestion from the beancount mail list (reddit).

CSV

Where can I find hledger CSV rules for my financial institutions ?

Look for a suitable rules file in the examples/csv/ directory on github. Or you can get the hledger source and look in examples/csv/.

If your financial institution is not there yet, please use these for inspiration, ask in the chat for help, and perhaps send a pull request contributing your new rules.

How do I make new hledger CSV rules ?

See the Importing CSV tutorial and the hledger manual > CSV format. (After checking for a pre-existing rules file in examples/csv/ in the hledger repo.) If possible, add your new rules file to that directory and send a pull request.

When importing CSV from two bank accounts, and there's a transfer between them, how do I avoid duplicate entries ?

You can have one of the rules files skip that transaction. Eg if you have checking and savings CSVs, in savings.csv.rules you might have a rule like

## already imported from checking
if TRANSFER FROM .*CHECKING
 skip

Other options: you could remove one of the entries manually. Or you could import both entries, but have them transfer to and from an imaginary third account (but this creates extra noise in your journal and reports).

Can I do arithmetic calculations in CSV rules ?

Eg, dividing the amount by 2 ? No; currently the best thing is to preprocess the CSV, adding the calculated values as a new field, before converting it with hledger.

Where can I find more help with CSV conversion ?

Study the whole CSV section in the manual carefully. Working with CSV has useful tips, eg for setting amounts. And of course, make use of the chat.

REPORTING

Why am I seeing some amounts without an account name in reports ?

When an account has a multi-commodity balance, hledger's default balance, print, and register reports, like Ledger's, will show the balance on multiple lines, with each commodity on its own line, but with the account name appearing only once (either top- or bottom-aligned, depending on report). For a clearer report, try balancesheet, incomestatement or cashflow, and/or --layout=bare, or restrict the report to a single currency with cur:SYMBOL.

Another reason you might see amounts without an account name: dropping too many account name parts with --drop.

How do I control the number of decimal places displayed ?

To set that temporarily, use the -c/--commodity-style option (one for each commodity, as needed). Eg, this shows dollars with two decimal places, ADA with six, and EUR with none:

hledger -c '$1000.00' -c '1000.000000 ADA' -c 'EUR 1000.' bal

To make it permanent, use commodity directives.

How do I display a decimal mark different from the one in the input file ?

Use -c/--commodity-style options (one for each commodity) to override the display style(s). Eg hledger bal -c '$1,00' displays dollar amounts with comma decimal marks, even if they use period decimal marks in the journal.

How do I report by financial year, not calendar year ?

Just specify the desired start date, eg hledger is -Y -b 2020/4/15 or hledger is -p 'yearly from 2020/4/15'. (With hledger <1.29, you can approximate this with -p 'every 12 months from 2020/4. or -p 'every 365 days from 2020/4/15'.)

How can I report (or generate transactions) on every Nth ... of ..., etc. ?

Use a period expression with one of the more complex report intervals.

How can I report (or generate transactions) on the last day of each month ?

Use "every 31st day". Eg:

hledger balancesheet -p 'every 31st day'

How do I show just deposits, or just withdrawals, in an account ?

Use amt: to match on amount sign. Usually you'll want to add an account query as well:

hledger register cash 'amt:>0'   # cash inflows
hledger register cash 'amt:<0'   # cash outflows

If you use aregister, it's like this (because of aregister's special first argument):

hledger aregister cash cash 'amt:<0'

How do I show the full entries for an account's deposits/withdrawals ?

Expanding the above reports to show the full transactions is difficult, because print is a transaction-based report, whose query matches if any postings are matched.

For now the best approach is to run hledger print -x ACCT and filter the output yourself, keeping only transactions where ACCT and a negative (or positive) amount appear on the same line. This requires a tool such as awk, and a regular expression that's good enough for your data. It's difficult to do this 100% reliably, avoiding false matches in descriptions, comments, subaccount names, balance assertions, commodity symbols. But here's an example that will work for most of us:

Show transactions where a cash account was increased:

hledger print -x cash | awk '/:cash.*?  [^-=]*[0-9]/' RS="\n\n" ORS="\n\n"

or decreased:

hledger print -x cash | awk '/:cash.*?  [^=]*-/' RS="\n\n" ORS="\n\n"

You can also do this kind of filtering with C-c C-f in Emacs ledger-mode, which is easier.

New: with a hledger dev build, you can now do

hledger print any:'cash amt:>0'

How do I show transactions between one account and another account ?

To show one transaction per line:

Use aregister ACCT1, with the other account as the query:

hledger aregister checking expenses:tax

To filter by direction, add 'amt:>0' or 'amt:<0':

hledger aregister checking expenses:tax 'amt:>0'

To see transactions in full:

Use print with an expr: query (requires hledger >=1.30):

hledger print expr:'checking AND expenses:tax'

Or with hledger <1.30, you can emulate that with not:not::

hledger print checking not:not:expenses:tax

How do I show a register or balance report between one account and another ?

The above won't work with the register or balance commands because these report on individual account postings, not whole transactions. Instead, run a print report to select transactions to use in a second report, like so:

hledger print checking | hledger -f- -I register expenses:tax

hledger print checking | hledger -f- -I balance expenses:tax

hledger print liabilities:mastercard | hledger -f- -I incomestatement

Complex multi-account transactions could muddle these reports a little; if that's a problem you might need to exclude those transactions or split them up.

What are some gotchas with piping hledger print into another hledger command ?

hledger print reproduces transactions, but it discards directives. The output will normally be a valid journal, but it can have a different meaning or even be unparseable due to:

  1. Loss of decimal-mark directives, which could disrupt number parsing.
  2. Loss of commodity directives declaring display precisions, which could disrupt transaction balancing.
  3. Loss of account directives declaring accounts' types, which could alter reports.
  4. Balance assertions which break because you have excluded transactions they depend on.

Workarounds:

  • Whenever you use -f - to read hledger print output, also add -I to ignore balance assertions. And write these flags separately (-If- does not work). So:

    $ hledger print ... | hledger -f- -I ...

  • Also recreate any required directives in the input stream. This is often not needed, but it depends on your data. If needed:

    • Keep those directives in their own file if possible (if directive scope rules allow it), which you can use as another input:

      $ hledger print ... | hledger -f- -I -f2023accounts.journal ...

    • Or find another way to pass the required directives along. Eg:

      $ { hledger print ...; grep '^[acd]' $LEDGER_FILE; } | hledger -I f- ...
$ { hledger print ...; grep '^[acd]' `hledger files` --no-filename; } | hledger -f- -I ...

CUSTOMISING

How can I save and reuse common options/arguments ?

Save them in a text file, with one option or argument per line, then include @FILE in your hledger command line. See argument files. This is superseded by...

Is there a config file ?

Yes, since hledger-1.40. See Config files.

How can I automatically use a journal file in the current directory ?

Perhaps you have journals in multiple project directories. If you use a standard filename, such as default.journal, you can run hledger with the -f default.journal option or set LEDGER_FILE to default.journal, perhaps in a script.

You can also use file glob patterns, like *.journal, in -f or LEDGER_FILE.

For more flexibility, you could use direnv to customise LEDGER_FILE per directory.

hledger will not search parent directories for a journal file, though there's probably a tool that will.

Related: #2194

With the new config file support, you could add -f FILE to a hledger.conf file in or above this directory.

SCRIPTING

How do I install more hledger scripts and add-on commands ?

git clone the hledger repo, and add the bin/ directory to your shell's PATH. See Scripts and add-ons.

How do I make new hledger scripts ?

Install the example Scripts and add-ons and find a suitable one to copy and modify. Also see Scripting. If your new script can be useful to others, consider contributing it with a pull request.

What's a good way to manage hledger scripts ?

Once you start defining handy scripts, they tend to proliferate and become hard to remember.

One solution is to gather scripts into a Makefile, and run them with make SCRIPT. This is very traditional and very common, but it has downsides. Listing scripts, handling arguments, portability, and dealing with make's special syntax are all a hassle.

As someone who has used make for a few decades, I urge, nay beg, you to install and use just instead. It is much better for this job and complements hledger and PTA very well. See the example Justfile and hledger and just.

HLEDGER-UI

With hledger-ui in iTerm2 on mac, why does Shift-Up/Shift-Down move the selection instead of adjusting the report period ?

iTerm2 by default doesn't recognise SHIFT-UP/SHIFT-DOWN keys correctly. (If this has changed in recent releases, please let us know.) Here's one way to fix it: iTerm2 > CMD-i > Keys > Key Mappings > Presets -> select "xterm Defaults" (not "Terminal.app Compatibility").