# Beancount and plain-text accounting glossary

Plain-text accounting borrows vocabulary from double-entry bookkeeping and adds a
handful of Beancount-specific words of its own. This glossary defines the terms you
will meet while reading these docs or your own ledger file, each with a short example
where it helps. Every entry has its own link, so you can point a teammate straight at
a definition.

## Account

An account is a named bucket that tracks one stream of value, written as a
colon-separated hierarchy under one of five root types: `Assets`, `Liabilities`,
`Equity`, `Income` or `Expenses`. The hierarchy is the whole organizing structure of
your books — `Assets:US:BofA:Checking` and `Expenses:Food:Restaurant` sort and roll up
automatically. Every account must be declared before it is used. See
[Beancount Language Syntax](https://beancount.io/docs/Basics/syntax) for the naming rules.

## Accrual basis

Accrual-basis accounting records income when it is earned and expenses when they are
incurred, regardless of when the cash actually moves. Cash-basis accounting does the
opposite: it recognizes both only when money changes hands. Accrual gives a truer
picture of a period's performance, which is why an invoice you sent in March belongs
to March even if the client pays in May.

## Amortization

Amortization spreads a single large payment across the periods it actually covers, so
each month carries its fair share of the cost. An annual insurance premium paid in
January is an expense of all twelve months, not just January. In Beancount you either
write the split postings by hand or generate them with a plugin — see
[Amortize](https://beancount.io/docs/Tips/amortize).

## Balance assertion

A balance assertion is a `balance` directive that states what an account's balance
must be at the start of a given date, so your bank statement becomes an automatic
check on your books. If the computed balance differs by more than the assertion's
tolerance, Beancount fails loudly with the expected and actual amounts. That tolerance
is one unit of the last decimal place you wrote — `4.27 RGAGX` accepts anything from
4.26 to 4.28 — and a `~` before the currency sets your own. Sprinkling one assertion
per account per statement is the single cheapest way to keep a ledger trustworthy.

```beancount
2026-01-01 balance Assets:US:BofA:Checking   4,321.00 USD
```

## Beancount

Beancount is an open-source double-entry accounting system whose ledger is a
plain-text file you edit in any text editor and validate with a command-line tool.
It gives you a strict, parseable syntax, a query language, and a web interface,
without a database or a proprietary file format. Because the ledger is text, it lives
happily in Git alongside your code. Start with
[Introduction to Beancount](https://beancount.io/docs/introduction-to-beancount).

## Beancount Query Language

Beancount Query Language, usually abbreviated BQL, is the SQL-like language you use to
ask your ledger questions. It runs over the parsed directives rather than a database,
so `SELECT account, sum(position) WHERE year = 2026` answers immediately from the same
file you edit. Read the
[query language guide](https://beancount.io/docs/Basics/beancount-query-language) for the full grammar.

## Booking method

A booking method is the rule Beancount applies when a reduction has to pick which
existing lots to draw down. Beancount 3.2.3 accepts seven names: `STRICT` (the
default, where you identify the lot yourself), `STRICT_WITH_SIZE`, `NONE`, `FIFO`,
`LIFO`, `HIFO` and `AVERAGE`. Set one per account on its `open` directive, or for the
whole file with `option "booking_method"`. Six of the seven are implemented: `AVERAGE`
parses, but raises `AVERAGE method is not supported` the moment it has to book a
reduction. The method you choose changes your realized capital gains, so pick the one
your tax jurisdiction expects and keep it stable.
[Inventory Management](https://beancount.io/docs/Basics/inventories) runs all seven over the same lots, and
publishes the ledger that fails under `AVERAGE`.

## Chart of accounts

A chart of accounts is the complete list of accounts your ledger uses, together with
the structure that organizes them. In Beancount there is no separate chart file — the
set of `open` directives *is* your chart of accounts. Designing it well early on saves
a lot of renaming later; see
[Industry-Specific Setups](https://beancount.io/docs/industry-specific-setups) for starting points.

## Close directive

A `close` directive marks the date after which an account may no longer be used, which
is how you retire a bank account or a paid-off loan without deleting its history. Past
transactions stay valid and reportable; only new postings are rejected. Closing unused
accounts keeps reports readable as a ledger ages.

```beancount
2026-03-31 close Assets:US:OldBank:Checking
```

## Commodity

A commodity is any unit of value your ledger tracks — a currency like `USD`, a stock
ticker like `AAPL`, a crypto asset like `BTC`, or something you invent such as
`VACATION-DAYS`. Beancount never converts between commodities behind your back, so an
amount is always a number paired with the commodity it is denominated in. An optional
`commodity` directive lets you attach metadata such as a name or an asset class.

## Cost basis

Cost basis is what you actually paid for a holding, recorded in the currency you paid
with and carried alongside the holding for as long as you own it. Beancount writes it
in braces — `10 AAPL {150.00 USD}` means ten shares acquired at 150 dollars each.
Double the braces and the number becomes the total rather than the unit price, so
`10 AAPL {{1,500.00 USD}}` records the same lot. Because the basis travels with the
position, capital gains fall out of the arithmetic when you sell. See
[Inventory Management](https://beancount.io/docs/Basics/inventories).

## Directive

A directive is one instruction in a Beancount file, usually dated, and directives are
what a ledger is made of. Twelve kinds carry a date: `open`, `close`, `balance`,
`price`, `note`, `document`, `pad`, `event`, `commodity`, `custom`, `query`, and the
transaction itself. A few carry none and act on the file rather than on a day —
`option`, `include`, `plugin`, and the `pushtag`/`poptag` pair. Beancount sorts the
dated ones by date before processing, so you can keep those in whatever order reads
best; an undated one takes effect where it is written.

## Double-entry bookkeeping

Double-entry bookkeeping is the practice of recording every economic event as at least
two matching entries, so that their weights always sum to zero. Money is never created
or destroyed — it only moves between accounts, which is why the technique catches
mistakes that a single-column list never would. A weight is a posting's own amount, or
its cost or price converted back into one currency, so two legs in different
commodities still cancel. Beancount enforces the rule strictly: a transaction whose
postings do not balance is an error, not a warning.

```beancount
2026-03-02 * "Bank" "Buy euros"
  Assets:US:BofA:EUR       100.00 EUR @ 1.08 USD
  Assets:US:BofA:Checking -108.00 USD
```

## Envelope budgeting

Envelope budgeting sets aside money for a purpose before you spend it, so each
category has its own limit instead of competing for one pooled balance. The name comes
from the paper envelopes people once filled with cash on payday. In a plain-text
ledger you model envelopes with dedicated accounts or budget directives — see
[Budgets](https://beancount.io/docs/Tips/budgets).

## Fava

Fava is the web interface for Beancount: charts, balance sheets, income statements, a
query editor and an entry form, served from your ledger file. It is read-mostly and
runs locally, so it changes how you *see* your books without changing how you record
them. beancount.io hosts a managed version alongside its own tooling; the
[UI Features](https://beancount.io/docs/Tips/ui-features) guide covers what you can do there.

## Inventory

An inventory is the collection of positions an account currently holds, each with its
own commodity and, where relevant, its own cost basis and acquisition date. A
brokerage account that bought the same stock three times holds three separate lots in
one inventory, not one blended number. Keeping lots distinct is what makes accurate
gain calculations possible.

## Journal

The journal is the chronological list of everything that happened in your books — the
raw stream of transactions, in date order, before any grouping or summarizing. It is
the view you scan when you want to answer "what did I actually do in March?". Fava's
journal page is usually the fastest place to spot a miscategorized entry.

## Ledger

A ledger is the complete set of accounting records for one entity, which in Beancount
means your plain-text file (plus anything it includes). The word doubles as the name
of the whole book of accounts and the name of the file itself. Because it is text, a
ledger can be diffed, reviewed, branched and merged like source code.

## Lot

A lot is one specific acquisition of a commodity, identified by its cost basis and
acquisition date. Buying the same ETF in January and again in June creates two lots,
and selling later means choosing which lot you are selling. Lots are the reason
Beancount can compute realized gains exactly instead of approximating them.

```beancount
2026-06-15 * "Broker" "Buy VTI"
  Assets:US:Broker:VTI     5 VTI {260.00 USD, 2026-06-15}
  Assets:US:Broker:Cash            -1,300.00 USD
```

## Narration

The narration is the free-text description of what a transaction was for, written as
the second quoted string on the transaction line. It is for humans: "Monthly rent",
"Groceries and household". Beancount does not parse it, but it is what you will read
when the entry no longer makes sense six months from now.

## Open directive

An `open` directive declares an account, the date it starts being usable, and
optionally the commodities it may hold and the booking method it uses. Beancount
requires every account to be opened before its first posting, which is what stops a
typo from silently creating a brand-new account. Restricting the allowed commodities
turns another whole class of mistakes into errors.

```beancount
2026-01-01 open Assets:US:Broker:VTI   VTI   "FIFO"
```

## Pad

A `pad` directive tells Beancount to insert whatever amount is needed to make the next
balance assertion on an account succeed, booking the difference to a second account.
It exists for exactly one job: opening a ledger part-way through life without
reconstructing years of history. Padding beyond that initial setup usually means a
real error is being papered over.

## Payee

The payee is who you transacted with, written as the first quoted string on a
transaction line. Keeping payees consistent — always `"Whole Foods"`, never sometimes
`"WholeFoods"` — is what makes payee-based reports and automated importers work.
Beancount treats the payee as optional; a transaction may carry only a narration.

## Plain-text accounting

Plain-text accounting is the practice of keeping your books in a human-readable text
file under version control, processed by open-source command-line tools. It trades a
point-and-click interface for durability, auditability and automation: your data
outlives any vendor, every change is a reviewable diff, and any script can read it.
Beancount, Ledger and hledger are the three best-known implementations.

## Plugin

A plugin is a Python module Beancount loads while processing your file, allowing it to
add, transform or validate directives before reports are built. Plugins are how
forecasting, amortization schedules and custom checks are implemented without changing
the core language. You enable one with a standalone `plugin` line at the top of your
ledger, never with an `option` — `option "plugin" "…"` is rejected with
`Option 'plugin' may not be set`. The [Forecast Plugin](https://beancount.io/docs/Tips/forecast-plugin) guide
walks through a real example.

## Posting

A posting is one leg of a transaction: an account, an amount, and optionally a cost or
price. What has to sum to zero across a transaction is not the raw amounts but their
weights: a plain amount weighs itself, `10 FUND @ 38.46 USD` weighs `384.60 USD`, and
`10 FUND {384.61 USD}` weighs `3,846.10 USD`, because single braces hold the cost of
one unit. At most one posting may leave its amount blank, in which case Beancount
computes the balancing figure for you. See
[Precision & Tolerances](https://beancount.io/docs/Basics/precision) for the full weight rules.

## Price directive

A `price` directive records the exchange rate between two commodities on a date, which
is how Beancount converts a holding to its market value in reports. A `price`
directive is pure reference data: it moves no money and belongs to no transaction. Do
not confuse it with the `@` price written inside a posting, which is arithmetic — it
gives `10 FUND @ 38.46 USD` a weight of `384.60 USD` and so decides whether the
transaction balances. Without price directives, a portfolio still balances at cost but
cannot be valued at market.

```beancount
2026-06-30 price VTI   271.40 USD
```

[Live Prices](https://beancount.io/docs/live-prices) supplies managed price directives for supported assets in hosted ledgers. Your own price wins for the same date and pair, including the reciprocal pair. A managed price on a later date can still apply to a later valuation.

## Reconciliation

Reconciliation is the act of proving that your books agree with an outside record such
as a bank or brokerage statement. In plain-text accounting it is largely mechanical:
add a balance assertion for each statement date and let the tool tell you whether the
numbers match. A ledger that reconciles cleanly every month is one you can file taxes
from without fear.

## Tags and links

Tags and links are the two labels you attach to transactions to group them outside the
account hierarchy: a tag with `#` marks a theme such as `#trip-japan`, and a link with
`^` ties related entries such as `^invoice-2026-014` together. Tags answer "show me
everything in this category"; links answer "show me the entries that belong to this
one event". Both are filterable in Fava and queryable in BQL — see
[Filtering and Searching](https://beancount.io/docs/Tips/filtering-and-searching).

## Transaction

A transaction is a dated economic event together with the postings that record it, and
it is the directive you will write most often. It carries a flag (`*` for confirmed,
`!` for needs-review), an optional payee, a narration, and two or more postings whose
weights sum to zero. Everything else in a Beancount file exists to declare, check or
annotate transactions.

```beancount
2026-02-14 * "Blue Bottle" "Coffee with Dana"
  Expenses:Food:Coffee      9.50 USD
  Assets:US:BofA:Checking  -9.50 USD
```

---

Still stuck on a word? The [Help Center](https://beancount.io/docs/help-center) indexes every guide on this
site, and the [Cheatsheet](https://beancount.io/docs/Basics/cheatsheet) puts the syntax for each directive
side by side.
