About beancount
Beanie Budgets keeps your money in a beancount ledger: a folder of plain text files you own, that plenty of other tools can read. It goes as far as you want it to. Tap a few buttons and never think about the format again, or bring a ledger you have kept for years and use the whole of it.
What beancount is
beancount is a plain-text, double-entry accounting format created by Martin Blais. Your whole financial history is plain text you can read, search, back up and keep forever, with no database and no proprietary format in the middle. It can be one file or a folder of them, split up however suits you. It is free and open source, and there is a whole ecosystem of tools around it.
beancount on GitHub · The official documentation · Fava, the web interface
Beanie Budgets is an independent app. The beancount project and Fava have not reviewed or endorsed Beanie Budgets, and are not otherwise affiliated with it. beancount was created by Martin Blais and is free and open source; this app reads and writes its file format, and we are glad to credit it.
What a ledger looks like
A transaction is a date, who it was with, and where the money moved from and to. The two sides have to add up to nothing, which is what double-entry means and what makes the arithmetic self-checking.
2026-09-14 * "Sainsbury's" "Weekly shop" Expenses:Food:Groceries 42.15 GBP Assets:Bank:Current -42.15 GBP
Accounts are opened before they are used, and you can assert a balance at a date so the file checks itself against your statement:
2026-01-01 open Assets:Bank:Current GBP 2026-01-01 open Expenses:Food:Groceries GBP 2026-10-01 balance Assets:Bank:Current 1284.60 GBP
Beanie Budgets writes all of this for you. You tap Add Transaction, choose the accounts by name, and type an amount. Most people never open the file.
The file is still there when you want it. Write a transaction by hand in any editor and the app reads it back and keeps it exactly as you wrote it, comments and arithmetic included. Nothing about starting simple closes the door on the rest of it later.
Beanie Budgets compatibility
Skip this unless you want it. It is here for people bringing an existing ledger, who want to know what we do with the parts of the format they already use. Every row is covered by a test that compares Beanie Budgets against bean-check and bean-query output on the same file, rather than against our own idea of what should happen. Where we differ from beancount, that is a bug, and we would like to hear about it.
Reads and writes means the app can create and edit it too. Reads means an existing one is understood and preserved exactly as you wrote it, but the app will not create one for you.
If you would rather see a working example than a row in a table, Supported syntax has one for each, checked against bean-check under both beancount 2.3.6 and 3.2.3 before that page was built.
Some of these stay read-only on purpose. Beanie Budgets is built for what is worth doing on a phone: recording what you spent, seeing where you are, and reading a report on the bus. Declaring a commodity or keeping a price history is editing work, and it belongs at a desk in a text editor. So we read those carefully, leave them exactly as you wrote them, and leave the writing to you.
Editing follows the same line. A transaction whose postings sit in more than one currency, or which balances through a cost basis rather than by its amounts adding up, or which leaves an amount for beancount to infer, opens with Delete and no Edit. That is deliberate. The editing form works in one currency with figures that offset, and rather than rewrite a transaction into a shape it can represent, losing what made it different, it declines to touch it.
So a share purchase written 100 VWRL {90.00 GBP} is read, valued, shown on Holdings and counted in your net worth, and stays exactly as you typed it. Recording a new one, or changing one, is work for wherever you already do it.
There is a way of tracking investments that suits a phone, and plenty of people keep a ledger this way. Record the money going in as an ordinary transaction, from your bank into an investment account, then use Correct Balance to bring that account to whatever your provider says it is worth. You get the balance, the trend and the net worth figure without recording a single lot.
| Construct | Support | Notes |
|---|---|---|
| Transactions | Reads and writes | Payees, narrations, tags, links, flags and metadata. |
| Postings | Reads and writes | Including leaving the number, the currency, or both for beancount to infer. A transaction with an inferred amount is read and counted in full, and offers Delete rather than Edit, since editing would spell out a figure you chose to leave implied. |
| Arithmetic amounts | Reads | 100.00 + 5.00, (4.00 + 1.00) * 3, thousands separators. Kept as you wrote them for as long as the amount is unchanged; the app's own entries are written as plain numbers. |
open | Reads and writes | Written when you add an account, and widened if you record a transaction from before it was opened. A booking method such as open Assets:Brokerage "FIFO" is kept. |
close | Reads | Kept, and rewritten correctly if you rename the account. It does not yet hide the account in the app. |
balance | Reads and writes | Including an explicit tolerance, 999.98 ~ 0.05 USD. |
pad | Reads and writes | Correct Balance writes a pad and balance pair for you, and the padding entry is worked out and included in balances. |
Cost bases {...} | Reads | Per-unit and total, kept exactly as written through an account rename. A disposal with empty braces takes the lot your booking method chooses. A transaction carrying one is read and valued, and offers Delete rather than Edit, so we never rewrite it. |
Prices @ and @@ | Reads | Kept exactly as written, and used to value a holding. A priced posting keeps its own units, as beancount does. |
| Booking methods | Reads | STRICT, FIFO, LIFO, HIFO, NONE and AVERAGE, per account or via option. |
price | Reads | Used as written or inverted, since a rate one way states the rate the other. Two rates are never combined into a chain, because beancount does not combine them either: a price has to be quoted in your ledger's own currency to reach it. |
commodity | Reads | Including an asset class declared in metadata, used by the Allocation report. |
note | Reads and writes | Kept through an edit, including a quote inside the text. |
document | Reads | Kept correct when you rename an account. The file it points at is not shown yet. |
include | Reads and writes | Nested, and with wildcards such as accounts/*.bean. The app adds one to your root file the first time it needs to. |
option | Reads and writes | Including operating_currency, booking_method and the inferred-tolerance options. A few are written for you when the app creates a new ledger from scratch. |
pushtag / poptag | Reads | The pushed tag reaches the transactions inside it, and stops at the pop. |
pushmeta / popmeta | Reads | As above, for metadata. Posting-level keys stay on their own posting. |
event, query, custom, plugin | Read past safely | Not interpreted, but they never stop a ledger loading and never affect your figures. |
Fava budget / fava-option | Reads and writes | The budget directive drives Budget Monitoring. |
| Forecast-plugin repeats | Reads and writes | #-flagged transactions tagged [MONTHLY UNTIL 2027-01-01] and similar. |
| Multiple currencies | Reads | Each account keeps its own currency, and a holding bought in one currency is valued in yours when your ledger quotes a price that reaches it. Where no price reaches it, we show the units held rather than a figure we cannot stand behind. |
| Transaction balancing | Reads | Within the tolerance beancount infers from how precisely you wrote the amounts. |
| File encodings | Reads | Windows line endings, a byte order mark, and Unicode throughout. |
The honest caveat: this table describes what is tested, not a guarantee that nothing is missing. We test against beancount's own parser test suite, against a 6,600 line ledger generated by bean-example, and against 88 ledgers whose every figure is compared with bean-check, bean-query and Fava output. Even so, the most useful reports have always come from people running their own ledgers and telling us what broke.
If you already have a ledger
Point Beanie Budgets at the folder your root file lives in and it reads what is there. Anything it does not change is left exactly as you wrote it, comments and arithmetic included.
What it writes is formatted its own way rather than matched to yours, in two visible respects. A new transaction is appended to the end of its file rather than slotted into date order, and its amounts line up with each other rather than with the column the rest of the file uses. Both are cosmetic: beancount sorts by date when it reads, and so do we. Matching your file's alignment would mean rewriting lines we have no reason to touch.
It does write a few things of its own, and you should know what before you point it at a ledger you care about:
- An
includeline in your root file, the first time it needs one. It keeps its own files in abeanling/folder beside your ledger, and that line is what pulls them in. - New transactions go into a file per year inside that folder, rather than into one of yours.
- An
opendirective's date is widened if you record a transaction from before the account was opened, since beancount would otherwise refuse the file. - Editing or deleting an entry rewrites those lines where they sit, in your file.
A copy of the whole folder is taken before any change, and you can restore it from Settings. See the FAQ for the full list of what lands in a folder and how sharing a ledger between devices works.