Guides · Firefly III

Firefly III import: CSV files with the Data Importer, step by step

Updated November 18, 2026 · 7 min read · By the Utilly team

Firefly III imports bank transactions through a separate app, the Firefly III Data Importer. It reads CSV files and CAMT.053 files, or pulls transactions from a bank data provider. It doesn't read PDF statements, and OFX and QIF aren't on its list of file types. For a CSV you tell the importer whether the file has headers, what the delimiter and date format are, and what each column holds. Here's the whole flow, the settings that cause most failed imports, how duplicate detection works, how to get PDF statements in, and free CSV test files with known totals.

Short answer: open the Firefly III Data Importer, choose a file import and upload the CSV (plus a saved configuration file, if you have one). On the configuration screen tick Headers if the first line holds column names, set the CSV delimiter and the Date format (Y-m-d for dates like 2026-09-01), pick a Default import account and choose content-based duplicate detection. Give each column a role (Date, Description, Amount, or ignore), then press Start Job twice: once to convert and validate, once to import. Free test files: a checking CSV (31 fictional transactions) and a credit card CSV (21).

See the statement behind the test files

Open Utilly's fictional September 2026 checking statement: every line, the balance check from 12,418.36 to 13,440.52, and the CSV download. Free, because the data is made up. The checking test file on this page holds those same 31 lines, so you know exactly what an import should bring in.

Checking CSVCard CSV

1. The test files

These files hold Utilly's fictional September 2026 checking and credit card statements as CSVs the Data Importer can read, so you can try an import into a test asset account and compare the result with known totals before you touch real data. No sign-up.

FileWhat's in itKnown totals
Checking CSVA Date, Description, Amount header row, then the 31 lines of the fictional checking statement20 payments 28,575.27; 11 deposits 29,597.43; net +1,022.16
Credit card CSVThe same header, then the 21 lines of the matching fictional card statement, by date19 charges 1,939.94; 2 credits 1,542.18; 397.76 more owed

The rows come from Utilly's fictional sample statements (explained on sample bank statement PDF), read by the same engine Utilly's converters use. Each CSV is comma-delimited with a header row and three columns: the date written year first (2026-09-01, date format Y-m-d), the statement description (commas and quote marks taken out), and the amount as one signed number with a period decimal. Money out is negative on both files, card charges included. The Data Importer's role reference says "Most of the time, the amount is stored both positive and negative. The data importer can handle this automatically." The files are plain ASCII text with Unix line endings, about 1.4 KB and 1 KB.

Date,Description,Amount
2026-09-01,ACH DEBIT GUSTO PAYROLL 0912,-6420.18
2026-09-01,STRIPE TRANSFER ST-K2M8Q4,3184.27
2026-09-02,CHECK 2041,-1850.00

2. What the Data Importer can import

Firefly III doesn't import files itself. Its documentation says "In order to import transactions into Firefly III, you'll have to install the Firefly III Data Importer", and that the importer "is a separate tool from Firefly III with its own installation and upgrade guides."

SourceFirefly III's documentation saysWhat it means for you
CSV"You can import CSV files from any source: your bank, YNAB, Tiller or any other source of financial data."The usual route. You set the layout and column roles (section 3)
CAMT.053Listed as the second supported file type; "For camt.053 there are less options for you to pick from per data field, since camt.053 standards are stricter."Use it if your bank exports camt.053 XML (common in Europe)
Bank connection"The data importer uses several third party data providers to connect to a range of banks world wide."Ongoing sync, separate from file imports
OFX, QFX, QIFThe file how-to lists only CSV and CAMT.053: "Other file types are not yet supported, but I am working on them."Convert to CSV first, for example with OFX to CSV or QIF to CSV
PDF"PDF files will never be supported."Convert the statement to CSV first (section 6)

3. Importing a CSV, step by step

Before you start, the file how-to asks you to know three things about the CSV: "Whether it has headers", "What the delimiter is" and "What each column contains". For the test files: yes, a comma, and Date, Description, Amount.

  1. Open the Data Importer, choose to import a file and upload the CSV. The CSV tutorial warns: "If the file contains any lines before the data starts, you must remove them manually." It also points to a GitHub repository of standard configuration files per bank; if yours isn't there, carry on without one.
  2. On the configuration screen, tick Headers if the first line holds column names (it does in the test files).
  3. Set the CSV delimiter. The documentation says "This is almost always a comma."
  4. Set the Date format in PHP date notation: Y-m-d for 2026-09-01, m/d/Y for 09/01/2026, Ymd for 20260901.
  5. Choose a Default import account, the asset account the lines belong to. The test files have no account column, so this is required. Optionally tick Rules to run your Firefly III rules on the import, and keep the Import tag so the whole import is grouped under one tag.
  6. Choose the duplicate detection method (section 5). The CSV tutorial suggests content-based duplicate detection for now.
  7. Give each column a role (section 4). If you ticked the option to map data, link names in the file to existing Firefly III accounts and categories.
  8. Press Start Job. The documentation explains the two steps: "First a conversion and data validation. Then, the data will actually be sent to Firefly III." When the conversion succeeds, press Start Job again to import.

Download the configuration file at the end. Firefly III's reference says "The data importer generates an import configuration file each time you import data. You can download the configuration file during or after the import." Upload it with next month's file and the delimiter, date format, roles and mappings are already set.

4. Column roles

"Each column must be given a role. You can of course, choose to ignore a column." The roles you need for a bank or card CSV:

RoleUse it forTest file column
DateThe transaction date. "Choose the date closest to the actual transaction." The format must match the Date format settingDate
DescriptionThe bank's text. Several description columns are joined togetherDescription
AmountOne signed amount column. Switch to the Amount (negated column) role "if the transactions get imported the wrong way around."Amount
Amount (credit / debit column)Banks that split money in and money out into two columns; give both columns this roleNot used
Bank specific credit/debit indicatorA column with a letter or word such as CR or DB next to an unsigned amountNot used
Opposing account (name)A payee or counterparty column, if your bank has oneNot in the test files
External ID / Internal referenceA unique transaction ID from the bank, for identifier-based duplicate checksNot in the test files
(ignore this column)Anything else, such as a running Balance columnNone to ignore

5. Duplicate detection

"The data importer will not import the same transaction twice", and it has two methods:

  • Content-based: Firefly III hashes each transaction as the importer prepared it and refuses one whose hash already exists. Changing the roles or mappings between imports changes the hash, so keep the same configuration file for the same bank.
  • Identifier-based: every transaction must have a unique identifier in a column, and the importer looks it up in Firefly III. Only use it if your bank's file has a real transaction ID.

Deleted transactions count too: "The Data Importer will also check deleted transactions when checking for duplicates." To re-import something you deleted, turn off duplicate detection or use the Purge button on the last tab of your profile first. Files with very few columns can also cause false duplicates, which is why the FAQ suggests adding a sequence column (1, 2, 3...) when rows aren't unique.

6. PDF statements

The Data Importer won't read PDFs. To bring in months you only have as PDF statements:

  1. Convert each statement with Utilly's bank statement PDF to CSV converter (card statements: credit card statement to CSV). The free preview shows every line and whether the statement balances before you download.
  2. The CSV has Date, Description, Amount and Balance columns with year-first dates. Tick Headers, use a comma delimiter and date format Y-m-d, give Date, Description and Amount their roles, and set Balance to (ignore this column).
  3. Import one month into a test asset account first (section 7) and compare it with the statement, then download the configuration file and reuse it for the other months.

7. Checking the import against known totals

Import the test files into a new asset account you don't rely on, then compare:

CheckChecking fileCredit card fileIf it's wrong
Transactions3121Fewer: some rows were treated as duplicates, or didn't parse
Money out28,575.27 (20)1,939.94 (19)A different total means a column has the wrong role
Money in29,597.43 (11)1,542.18 (2)Same as above
Change in balance+1,022.16397.76 more owedThe opposite sign means the amounts were read the wrong way round (use Amount (negated column))
DatesSept 1–30, 2026Sept 1–30, 2026Everything dated today means the Date role or format is wrong
Statement balance12,418.36 → 13,440.52owed 2,846.12 → 3,243.88Set the test account's opening balance to match the statement

The data is fictional (Example Community Bank and Sample Customer LLC don't exist; both statements say SAMPLE STATEMENT, FICTIONAL DATA FOR DEMONSTRATION ONLY). Replace every row before using a template for real.

8. Problems and fixes

SymptomWhat Firefly III's documentation says
All transactions are imported as todayMark the date column with the Date role and make the date format match the file, for example Y-m-d for 2023-09-17
Amounts like 3.123,12 aren't readSet FALLBACK_LOCALE=de_DE in the importer's environment variables
Expenses imported as incomeGive the amount column the Amount (negated column) role
Import fails on stray linesRemove any lines before the data, and extra header rows some banks repeat every 100 rows
504 Gateway TimeoutThe web page times out after about 600 seconds; the import carries on, but use smaller batches
Rows skipped as duplicatesToo little data to tell rows apart: add a sequence column, or check whether the transaction was deleted (deleted ones still count)
Lots of (no name) or (no description)The bank file has little data; use rules to fill in descriptions and accounts after the import

Comparing apps? Actual Budget also maps a signed Amount column, Spendee imports CSV and Excel files into cash wallets from its web app, GnuCash and KMyMoney map CSV columns in a preview, and HomeBank and PocketSmith also take OFX and QIF.

Get PDF statements into Firefly III

PDF statements, downloaded or scanned, get a free preview with the balance check, no sign-up. Download a clean CSV with year-first dates and one signed Amount column, ready for the Data Importer. Files are processed in memory and not stored.

Utilly isn't affiliated with Firefly III. The steps and quotes above are from the official Firefly III documentation, checked November 18, 2026; the test files weren't imported into a live Firefly III installation, and screens may differ. Sources: Import a basic CSV file, How to import files, Data field roles, Duplicate detection, How to handle (missed) duplicates, JSON configuration file, Common data import issues, Firefly III Data Importer, Importing data. If a screen differs, follow Firefly III's current documentation.

FAQ

What files can Firefly III import?

Firefly III imports through the separate Firefly III Data Importer, which reads CSV and CAMT.053 files and can also pull transactions from third-party bank data providers. Its documentation says PDF files will never be supported, and OFX and QIF aren't on its list of file types.

How do I import a CSV into Firefly III?

Open the Data Importer, upload the CSV, set Headers, the CSV delimiter and the date format (Y-m-d for 2026-09-01), choose a default import account and duplicate detection, give each column a role such as Date, Description and Amount, then press Start Job to convert and again to import.

Why are all my Firefly III transactions imported as today?

The date column isn't marked with the Date role, or the date format doesn't match the file. A date like 2023-09-17 needs the format Y-m-d, in PHP date notation.

How do I stop duplicate transactions in Firefly III imports?

Use content-based duplicate detection and keep the same configuration file for the same bank, since changing roles or mappings changes the hash. The importer also checks deleted transactions, so purge them first if you need to re-import.

Can Firefly III import OFX or QIF files?

Not with the Data Importer: its file how-to lists only CSV and CAMT.053 and says other file types aren't supported yet. Convert the OFX or QIF file to CSV first, then import the CSV.

Can Firefly III import a PDF bank statement?

No. The Data Importer documentation says PDF files will never be supported. Convert the PDF statement to CSV first, then import the CSV with Date, Description and Amount roles.

Related tools

  • Bank reconciliation checker: compare a bank statement to your books and list missing, duplicate and mismatched transactions.
  • Receipt to CSV: turn PDF or photo receipts and invoices into CSV, Excel, or QuickBooks and Xero bill imports.