# Beancount FAQ: Plain-Text Accounting Questions

The questions below come from the plain-text accounting community — Reddit, Hacker News,
the Beancount mailing list — and cover how the *practice* works. For questions about the
Beancount.io service itself (pricing, plans, support, account management), see the
[product FAQ](/faq).

## Starting out

### How much accounting do I need to know before I start?

About five concepts, not a degree. You need the five account types (assets, liabilities,
equity, income, expenses), the idea that every transaction moves value between at least two
of them, and the rule that a transaction must balance. Beancount enforces the rest for you —
it flags any transaction whose numbers do not add up as an error instead of accepting it
silently, so the software catches the mistakes a beginner would otherwise miss.

Start with the [Introduction to Beancount](https://beancount.io/docs/introduction-to-beancount), keep the
[Glossary](https://beancount.io/docs/glossary) open in a tab, and add your first transactions in the
[Quick Start](https://beancount.io/docs/Basics/getting-started).

### Where are debits and credits in Beancount?

Beancount does not use the words "debit" and "credit" at all — it uses signed numbers that
must sum to zero. Money leaving an account is negative, money arriving is positive, and a
transaction is valid when its postings cancel out. This is the same double-entry
bookkeeping accountants do, with the vocabulary that confuses newcomers removed.

If you have used traditional accounting software, the translation is: a debit is a positive
number and a credit is a negative one. See the [Language Syntax](https://beancount.io/docs/Basics/syntax) reference
for how postings are written, or
[Debits and Credits Explained](/blog/2026/04/08/debits-and-credits-explained-a-plain-english-guide-for-small-business-owners)
for the accounting background in plain English.

### Why do transactions have to balance to zero?

Because money always comes from somewhere, and the zero-sum is what turns that fact into an
error check. If you spend \$40 on groceries, that money left a bank account — recording both
halves means the two must cancel, and any typo in either amount is flagged as an error
instead of quietly producing a wrong balance.

This is why a plain-text ledger is more trustworthy than a spreadsheet of expenses: the
structure itself is self-checking. A balance assertion is the related mechanism that
checks your ledger against reality.

### How do I set up my opening balances?

Record a transaction on your start date that moves each account's current balance from
`Equity:Opening-Balances`, then add a `balance` assertion to lock it in. You do not need to
reconstruct your financial history — pick a start date, take the balances as they are that
day, and go forward from there.

The [Quick Start](https://beancount.io/docs/Basics/getting-started) walks through a complete opening-balance
example.

### How detailed should my chart of accounts be?

Start coarse and split only when a finer split would change a decision. Twenty or so
accounts is plenty to begin with; if you find yourself wondering whether "Expenses:Food"
should separate groceries from restaurants, the useful test is whether you would actually do
something differently knowing the split.

Renaming and splitting later is a find-and-replace in a text file, so the cost of starting
simple is low. Account names nest, so you can start with a broad category and split it into
sub-accounts later without rewriting history — see
[How to Design a Chart of Accounts](/blog/2026/03/16/how-to-design-chart-of-accounts-small-business-guide)
if you want a structure to copy.

## Why plain text?

### Why use plain-text accounting instead of a spreadsheet?

A spreadsheet cannot tell you when it is wrong. Plain-text accounting enforces double-entry,
so every transaction is self-checking, and the file stays greppable, diffable, and
scriptable for as long as text files exist. You also get real version history: `git log` on
your ledger shows exactly what changed, when, and why.

The practical difference shows up with multiple accounts, currencies, or investments, where
a single-entry spreadsheet silently drifts out of true. See
[Transparent and Auditable Accounting](https://beancount.io/docs/Solutions/transparent-and-auditable).

### Isn't double-entry bookkeeping overkill for personal finance?

If you only want to know what you spent on coffee, yes — a spreadsheet is fine. Double-entry
earns its keep the moment you have several accounts, a mortgage, a brokerage, or more than
one currency, because those are exactly the situations where single-entry tracking loses
money without telling you.

A useful way to think about it: double-entry is a checksum for your finances. See the
[Introduction](https://beancount.io/docs/introduction-to-beancount) for the longer case.

### Do I have to use the command line?

No. [Fava](/fava) is a full web interface over the same text file —
balance sheets, income statements, charts, and transaction entry — and Beancount.io runs it
for you with your ledger in the cloud. The text file remains the source of truth, so you can
use the web UI day to day and drop to a terminal only when you want to. If you do prefer a
terminal, the `bea` command line creates, checks and reports on that same file — see the
[CLI quick start](https://beancount.io/docs/Basics/bea-cli).

See [UI Features](https://beancount.io/docs/Tips/ui-features) for what the interface can do, or
[try the live demo](/demo).

## Getting your data in

### How do I get my bank transactions into Beancount?

Most people import 80–95% of transactions and hand-enter the rest. In rough order of
reliability: a direct OFX/QFX download from your bank, a CSV export plus import rules, an
aggregator connection, and — only as a last resort — a PDF statement converted to CSV.
Beancount.io's [bank sync](/bank-sync) handles the connection and
categorization for you.

Expect to write or adjust a rule per institution: bank CSV exports are notoriously
inconsistent, and a merchant name containing an unescaped comma is a real and common
problem. See [Smart Import](/smart-import) for the automated path.

For a one-off file, two free browser converters do the mechanical part without uploading
anything: [CSV to Beancount](/tools/csv-to-beancount) for spreadsheet exports, and
[OFX & QIF to Beancount](/tools/ofx-to-beancount) for the `.ofx`, `.qfx`, `.qbo` and `.qif`
downloads banks offer when they offer no CSV at all.

### How do I avoid importing the same transaction twice?

Importers deduplicate against entries already in your ledger, matching on date, amount, and
payee, and flag anything ambiguous for you to confirm rather than guessing. The usual
workflow marks uncertain imports as pending so you review them before they become part of
the permanent record.

OFX makes this easier than CSV: every transaction carries a `FITID` the bank keeps stable
across downloads, so an importer can match on identity instead of inference — the
[OFX converter](/tools/ofx-to-beancount) preserves it as an `id:` metadata field.

The other half of the answer is transfers: money moving between two accounts you own shows
up in *both* banks' exports. Record it once as a single transaction with two postings.

### Do I have to give a third party my bank login?

No — and for many people this is the reason to use plain-text accounting at all. You can
export OFX or CSV from your bank yourself and never hand credentials to an aggregator. If
you prefer automated sync, Beancount.io uses a bank-sanctioned aggregator rather than
storing your online banking password.

Read the details on the [security page](/security).

### How do I reconcile my ledger against my bank statement?

Add a `balance` assertion for the statement's closing figure, dated the day **after** the
closing date. Balance assertions are evaluated at the start of their date, so the next
morning's assertion is what includes every transaction through the last statement day. If
your ledger disagrees with the bank, `bea check` reports a `Balance failed` error and exits
non-zero, which turns reconciliation from a manual comparison into something the software
checks every time it runs.

A monthly cadence is enough for most people. See
[Filtering and Searching](https://beancount.io/docs/Tips/filtering-and-searching) for tracking down a
discrepancy.

## Currencies and investments

### How does Beancount handle multiple currencies?

Natively, and this is one of its strongest advantages over consumer finance apps. Every
amount carries its currency, accounts can hold several at once, and conversions are recorded
explicitly with `@` for a price or `{}` for a cost, so an exchange-rate change never silently
rewrites your history.

Nothing is converted behind your back — you always see both the original currency and the
converted value. See [Language Syntax](https://beancount.io/docs/Basics/syntax),
[Precision & Tolerances](https://beancount.io/docs/Basics/precision), and
[Multi-Currency Accounting](/blog/2026/03/19/multi-currency-accounting-guide-small-business-international)
for the bookkeeping side.

### How do I keep valuation prices up to date?

Use [Live Prices](https://beancount.io/docs/live-prices) for supported assets in a hosted Beancount.io ledger, or fetch quotes into local price files for upstream Beancount and Fava. The picker lets you choose a quote currency and copy managed includes. Compatible `bea` versions also support managed includes; the setup guide links to their instructions.

Managed prices affect market valuation, not transaction amounts or cost basis. Your own price takes priority for the same date and pair. Refreshes can use stale cached prices during an outage, and a later quote cannot fill a missing historical valuation date.

### How do I track cost basis and capital gains?

Record purchases with a cost in braces — `10 AAPL {150.00 USD}` — and Beancount tracks each
lot separately. When you sell, you say which lot you are reducing, and the capital gain falls
out of the arithmetic automatically instead of being something you compute by hand.

Beancount supports STRICT, FIFO, LIFO, and NONE booking methods. Average-cost booking is
parsed but **not fully implemented** — if your tax jurisdiction requires average cost, plan
to track it with a plugin or explicit lots. See
[Inventory Management](https://beancount.io/docs/Basics/inventories).

### How do I record crypto trades and their cost basis?

Exactly like any other commodity: a cryptocurrency is a unit with a cost, so the same lot and
booking machinery applies. A swap of one token for another is a single transaction that
reduces one lot and opens another, which is also how you get the realized gain that most tax
authorities want reported.

See [Cryptocurrency Portfolio Tracking](https://beancount.io/docs/Solutions/cryptocurrency-portfolio-tracking) and
the ready-made [crypto templates](https://beancount.io/docs/Tips/cryptocurrency-templates-examples).

## Business and freelance books

### Can I use Beancount for a small business, or is it only for personal finance?

Businesses do use it, including companies with hundreds of thousands of transactions. It
handles accrual accounting, multi-entity structures, and the reports an accountant expects.
The honest limits are that there is no multi-user concurrent editing, no built-in invoicing
UI, and no accounts-payable approval workflow — it is a ledger, not an ERP.

See [Industry-Specific Setups](https://beancount.io/docs/industry-specific-setups) and the
[Open Ledger](/open-ledger) showcase of real company books.

### Should I keep separate ledgers for personal and business?

Keep them separate — either as distinct top-level account trees in one file or as two files
combined with `include`. Mixing them makes the business's income statement meaningless and
makes tax time harder, and separating them costs nothing up front.

Two files is usually the cleaner choice once the business has its own bank account. See
[Multi-File Support](https://beancount.io/docs/Tips/multi-file-support).

### How do I handle invoices and accounts receivable?

Model receivables as an asset account and payables as a liability, then record the invoice
when you issue it and the payment when it arrives — that is accrual accounting, and Beancount
supports it directly. What it does not have is an invoicing interface: it tracks what you are
owed, it does not generate or send the invoice.

See [Financial Reporting Templates](https://beancount.io/docs/financial-reporting-templates) for the report side,
[Industry-Specific Setups](https://beancount.io/docs/industry-specific-setups) for worked examples, and
[Understanding Accounts Receivable](/blog/2025/08/12/understanding-accounts-receivable)
for the concepts.

### How do I hand my books to my accountant at tax time?

Export the reports rather than the ledger. Your accountant almost certainly does not want a
text file — they want an income statement, a balance sheet, and a transaction list, which you
can produce as CSV or PDF from the web interface or with a query.

See the [Tax Preparation Guides](https://beancount.io/docs/tax-prep-guides),
[Financial Reporting Templates](https://beancount.io/docs/financial-reporting-templates), and
[Query with SQL](https://beancount.io/docs/Basics/beancount-query-language) for pulling exactly the numbers they ask
for.

## Tools and ecosystem

### How do Beancount, Ledger, and hledger differ?

All three are plain-text double-entry systems with similar file formats. Ledger is the
original and the most permissive parser; hledger is a Haskell reimplementation known for
friendly CSV import rules and documentation; Beancount has the strictest parser and the
strongest support for investments, lots, and multiple currencies, plus a Python plugin API.

Strictness is the real trade-off: Beancount refuses to load a file it finds ambiguous, which
catches errors early at the cost of being fussier. See
[Beancount vs Ledger CLI](/compare/beancount-vs-ledger-cli) and
[Beancount vs hledger](/compare/beancount-vs-hledger).

### Does Beancount do envelope budgeting like YNAB?

Not natively — this is a genuine gap rather than a hidden feature. Beancount's built-in
budgeting is limited, and people who want strict envelope behaviour typically use a community
plugin or model envelopes as accounts.

If envelope budgeting is the main thing you want, read
[Beancount vs YNAB](/compare/beancount-vs-ynab) before switching. For
what does work today, see [Budgeting in Beancount](https://beancount.io/docs/Tips/budgets).

### Can I attach receipts to transactions?

Yes. The `document` directive links a file to an account and date, and the web interface lets
you upload and browse those documents alongside the transactions they belong to. Receipts
stay as ordinary files on disk, so they are as portable as the ledger itself.

See [UI Features](https://beancount.io/docs/Tips/ui-features).

### Is there a mobile app?

Yes — Beancount.io publishes [iOS](/beancount-ios) and
[Android](/beancount-android) apps for viewing your ledger and capturing
transactions on the go, which is the gap most plain-text setups leave open.

For quick capture without an app, many people record a rough note and reconcile it into the
ledger later.

### How large can a ledger get before it slows down?

A decade of personal finances is a few megabytes and loads in well under a second. Beancount
recomputes balances from the full transaction history on each load, and that stays fast into
the hundreds of thousands of entries. Past that the limit is editing and diffing comfort, not
load time: splitting by year with `include` keeps individual files small, but the included
files still form one combined ledger that Beancount loads and recomputes in full, so it is a
file-organization convenience rather than a speed-up or a way to keep separate books.

See [Multi-File Support](https://beancount.io/docs/Tips/multi-file-support) for how to split a growing ledger.

## Still stuck?

The [Help Center](https://beancount.io/docs/help-center) indexes the full documentation, and the
[Glossary](https://beancount.io/docs/glossary) defines any term above that was unfamiliar.
