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.
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 refuses to load a file whose transactions do not add up, so the software catches the mistakes a beginner would otherwise make silently.
Start with the Introduction to Beancount, keep the Glossary open in a tab, and add your first transactions in the Quick Start.
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 reference for how postings are written, or Debits and Credits Explained 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 makes the file fail to load 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 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 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.
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 for the longer case.
Do I have to use the command line?
No. 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.
See UI Features for what the interface can do, or try the live 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 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 for the automated path.
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.
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.
How do I reconcile my ledger against my bank statement?
Add a balance assertion with the statement's closing balance and date. Beancount will
refuse to load the file if your ledger disagrees with the bank, 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 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, Precision & Tolerances, and Multi-Currency Accounting for the bookkeeping side.
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.
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 and the ready-made crypto templates.
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 and the 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.
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 for the report side, Industry-Specific Setups for worked examples, and 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, Financial Reporting Templates, and Query with SQL 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 and 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 before switching. For what does work today, see Budgeting in Beancount.
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.
Is there a mobile app?
Yes — Beancount.io publishes iOS and 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, splitting by year with include keeps things
comfortable.
See Multi-File Support for how to split a growing ledger.
Still stuck?
The Help Center indexes the full documentation, and the Glossary defines any term above that was unfamiliar.