Migrate from QuickBooks to Beancount: a cutover guide

Pick a cutover date, export the QuickBooks trial balance for the day before it, and open your Beancount ledger with one pad and one balance per balance-sheet account. When bea check passes and the equity balance matches QuickBooks, your books have moved. Everything after the cutover is recorded in Beancount.

This guide works for QuickBooks Online and QuickBooks Desktop. It does not depend on a QuickBooks importer, because none ships with Beancount. You move balances first, then decide how much history to bring along.

If you are still deciding whether to switch, read Beancount vs QuickBooks first.

1. Decide the cutover date and what you keep​

Choose the first day of a fiscal year, such as 2026-01-01. A year boundary keeps one tax year in one system. It also means your first Beancount income statement starts from zero.

Decide now how much history Beancount should hold:

• Balances only. Open at the cutover and keep the QuickBooks reports as your archive for earlier years. This is the fastest path, and the rest of this guide assumes it.
• Yearly summaries. Add one summary entry per past year from each year's trial balance. Your multi-year reports then work in Beancount.
• Full transaction history. Convert the General Ledger export with a script. This is the most work, and section 5 explains what it involves.

Finish reconciling every bank and card account in QuickBooks up to the day before the cutover. An unreconciled balance moves its error into your new ledger.

2. Export from QuickBooks​

You need three reports, all ending on the day before the cutover (2025-12-31 in this guide):

QuickBooks Online. Go to Reports, then Standard reports, and open each report by name. Select Export/Print, then Export to Excel. The Account List is the chart of accounts report. The Export data tool under Settings, in the Tools column, exports a set of reports and lists as Excel files in one zip file. Intuit documents both paths in Export your QuickBooks Online data.

These QuickBooks Online exports are Excel files. Open each one in a spreadsheet and save a CSV copy if a script will read it.

Attachments are exported separately. In QuickBooks Online, go to Settings, then Attachments, select the files, and choose Batch actions then Export. Keep the zip with your archive.

QuickBooks Desktop. On Windows, open each report from Reports, then Reports Center. Select Excel, then Create New Worksheet. The next window can save an Excel workbook or a CSV file directly, as described in Export reports as Excel workbooks. Desktop can also export lists, including the chart of accounts, as an IIF file: File, then Utilities, then Export, then Lists to IIF Files. IIF export covers lists only. Intuit states that you can import transactions but cannot export them, as explained in Export, import, and edit IIF files.

Keep the original exports unchanged. They are your evidence if a number is questioned later.

3. Map accounts to a Beancount hierarchy​

Beancount has five root accounts. Every QuickBooks account type lands under one of them:

Account names start with a capital letter and contain no spaces, so "Office Supplies" becomes Expenses:Office-Supplies. QuickBooks sub-accounts become deeper segments, such as Expenses:Vehicle:Fuel.

Retained Earnings and Opening Balance Equity collapse into one Equity:Opening-Balances account. Beancount computes current-year earnings from your income and expense accounts, so no separate retained-earnings account needs to be carried forward.

4. Open the ledger at the cutover​

This example company has a four-line trial balance on 2025-12-31. Income and expense lines are already folded into Retained Earnings. QuickBooks Online does the same itself when a new fiscal year starts, as described in View retained earnings account details.

Save this as main.bean:

option "operating_currency" "USD"
 
2025-12-31 open Assets:Bank:Checking USD
2025-12-31 open Assets:AccountsReceivable USD
2025-12-31 open Liabilities:CreditCard:Visa USD
2025-12-31 open Equity:Opening-Balances USD
 
; Opening balances from the QuickBooks Trial Balance as of 2025-12-31
2025-12-31 pad Assets:Bank:Checking Equity:Opening-Balances
2025-12-31 pad Assets:AccountsReceivable Equity:Opening-Balances
2025-12-31 pad Liabilities:CreditCard:Visa Equity:Opening-Balances
 
2026-01-01 balance Assets:Bank:Checking 12450.00 USD
2026-01-01 balance Assets:AccountsReceivable 3200.00 USD
2026-01-01 balance Liabilities:CreditCard:Visa -1875.40 USD
2026-01-01 balance Equity:Opening-Balances -13774.60 USD

Each pad asks Beancount to insert the entry that makes the next balance assertion true. The balancing side of every pad goes to Equity:Opening-Balances. A balance assertion is checked at the start of its date, so the pads are dated the day before the cutover.

Debits become positive numbers and credits become negative ones. That is why the Visa balance is -1875.40 USD.

The last line is the tie-out. Equity must come to -13774.60 USD, the Retained Earnings credit. A mistyped asset or liability figure changes the padded equity, and that assertion fails.

For a real company, add one open, one pad and one balance for every balance-sheet account on the trial balance. Split A/R and A/P into one sub-account per customer or vendor if you track open invoices by name.

5. Bring history in​

After the cutover, record new activity in Beancount. Bank and card statements are the main source. Convert a bank CSV export in the browser with the CSV to Beancount converter, or use the bank import guide for the command line.

Past years are optional. There is no one-click import from a QuickBooks General Ledger export. Moving that history is a scripted or manual mapping step:

1. Save the General Ledger export as CSV.
2. Group its rows into transactions by date and transaction number.
3. Rename each account with your step 3 mapping.
4. Write each group as a Beancount transaction whose postings sum to zero.

If you bring history in, open the accounts at the start of that history instead of the cutover. Then keep the 2026-01-01 balance assertions. They prove that the converted history arrives at the same balances QuickBooks reported.

6. Verify against QuickBooks​

Check the ledger, then list every balance:

bea --file main.bean check
bea --file main.bean query "SELECT account, sum(position) GROUP BY account ORDER BY account"

bea check reports no errors. The query returns four rows: Assets:AccountsReceivable at 3200.00 USD, Assets:Bank:Checking at 12450.00 USD, Equity:Opening-Balances at -13774.60 USD, and Liabilities:CreditCard:Visa at -1875.40 USD. Compare each row with the QuickBooks Trial Balance line by line, with credits as negative numbers.

New to the command line? Install bea with the CLI quick start.

7. What does not come across​

A ledger migration moves accounting balances and history. It does not move the operations QuickBooks runs around them:

• Invoices and payment links. Open invoices remain as A/R balances. Use a separate invoicing service from now on.
• Payroll. Pay runs, tax forms and employee records stay with your payroll provider.
• Sales-tax filings. Beancount records the liability. Filing remains a separate task.
• Attachments. Receipts and documents come out in their own zip export, not in the reports.
• Bank-feed rules and reconciliation history. Rebuild categorization as import rules.

The comparison page says it plainly: do not choose Beancount on the assumption that a few plugins recreate the entire QuickBooks operating suite. Choose it when the ledger itself is your long-lived system of record.

Running a small business on Beancount? See Beancount.io for small business for hosted ledgers, Bank Sync and accountant collaboration.