hledger CSV: do the rules import amounts or balances?

When a hledger bank import looks too large, check whether the CSV rules map transaction amounts or running balances. A running balance describes the account after a movement; importing each balance as another movement produces a different journal.

For PDF-only statements, LocalExtract can export a local transaction CSV. Its amount field still needs review and an explicit hledger rule; it does not create a ready-classified journal. The CSV columns are date,description,amount.

Inspect the whole file before the new-only import

The hledger 1.52 CSV documentation distinguishes full conversion from importing only unseen transactions. Keep the original CSV and matching .rules file. Confirm the actual fields, date-format, account1 and amount direction.

Use hledger -f FILE.csv print to inspect all converted transactions. Use hledger import FILE.csv --dry-run separately to inspect the new candidates selected by import tracking. An empty new-only preview does not establish that the rules correctly interpret all rows. Run these commands only against your intended files and journal configuration; no hledger command has been executed for this article.

Use amount1 for movement and balance1 for a check

Where an explicit amount is available, map the signed bank movement to amount1. A balance1 value then creates a balance assertion, checking the resulting account balance rather than adding that value as a payment.

If the amount is absent, a balance can instead create a balance assignment. That asks hledger to infer a movement needed to reach a balance, which is not equivalent to importing the bank’s stated amount. The import command cannot generally use balance assignments depending on preceding journal balances. Prefer explicit transaction amounts when supplied; do not silently replace them with running balances.

Compare a consecutive pair in the bank’s currency

This invented account begins at 100. The CSV then supplies:

The two movements total +22, and 100 + 22 = 122. Summing the balance column gives 252, which is not the net movement. A proper balance assertion also needs the correct opening history and account currency; two plausible numbers alone do not prove it will pass.

The synthetic amount/balance worksheet tests this arithmetic and a wrong-column counterexample in Python. It does not execute hledger or prove that a particular bank CSV parser is correct.

Review the other posting too

Inspect both the bank posting and its opposing account in the full-file output. A generated expenses:unknown or income:unknown is still awaiting classification; balanced syntax does not complete bookkeeping. Confirm dates, signs and document references before authorizing an import.

For localized date/decimal cleanup, see the CSV locale guide. For a skipped older correction, use the separate .latest guide. This page addresses the rules’ amount/balance meaning. Prepare a PDF source locally if suitable original transaction data is unavailable.

Official hledger 1.52 documentation checked October 16, 2026.