Firefly III: CSV Import or Bank Connection?

Firefly III supports both CSV file imports and direct bank connections, but the two methods are not equally mature or universally available. CSV import is a built-in, fully supported feature that works with any bank that can export a CSV or similar file, while direct bank connections rely on third-party services (Spectre, Salt Edge, or Nordigen) that may not support your specific bank and require additional setup. For most users, CSV import is the more reliable and recommended starting point.

Background: What Firefly III Is and Why Imports Matter

Firefly III is a free, open-source personal finance manager that focuses on double-entry bookkeeping, budgeting, and clear visual reports. Since it is self-hosted, it does not automatically have access to your bank data—you must get transactions in somehow. The two official ways are importing a file (CSV, OFX, or QIF) or connecting directly to your bank via an API. The import process is handled by a separate component called the Firefly III Data Importer, which you run alongside the main application, either as a Docker container or as a standalone tool.

How CSV Import Works

CSV import is a manual but flexible process. You log into your bank’s website, download a statement in CSV (or sometimes OFX/QIF) format, and upload it to the Data Importer. The importer lets you map columns (date, amount, description, etc.) and set rules for how transactions should be categorized. You can save these mapping configurations and reuse them for future imports, which makes the process faster after the first time.

Key points:

• Works with any bank that offers a downloadable statement file.
• You control the file format and the mapping—no dependency on third-party APIs.
• You must manually download and upload each time (or automate with scripts if you are technical).
• Supports CSV, OFX, QIF, and even some bank-specific formats after configuration.

How Direct Bank Connections Work

Direct connections use the Firefly III Data Importer with a service that provides bank APIs. Currently, Firefly III officially supports three providers: Spectre, Salt Edge, and Nordigen (now part of GoCardless). These services act as intermediaries—they connect to your bank, retrieve transactions, and pass them to Firefly III. You need to create an account with one of these providers, get API credentials, and configure them in the Data Importer. The connection is then “direct” in the sense that you don’t download files, but it is not a native integration with your bank.

Important limitations:

• Not all banks are supported by all providers—you must check coverage.
• You must trust a third-party service with your banking credentials (or use the provider’s own authentication flow).
• Some providers are free (Nordigen is free for personal use), others charge fees after a trial.
• Connections can break if your bank changes its API or if the provider discontinues support.

How to Choose Between CSV and Bank Connection

Your choice depends on your bank, your technical comfort, and how often you need updates.

• Choose CSV import if your bank is not supported by the providers, if you prefer not to share credentials with a third party, or if you import only occasionally (e.g., monthly).
• Choose a direct connection if your bank is supported, you want more automated updates, and you are comfortable setting up API credentials.
• Consider a hybrid approach: use CSV for initial setup and direct connection for ongoing updates, or vice versa.

For most people, starting with CSV is easier because it requires no additional accounts and works immediately. If you later find the manual downloads tedious, you can explore direct connections.

Common Problems and Troubleshooting

Both methods have known issues. For CSV import, the most common problems are:

• Date formats that don’t match the importer’s expected format—you can set a custom format in the mapping.
• Negative amounts for withdrawals vs. expenses—you may need to switch the sign or use the “expense” column.
• Duplicate transactions if you import the same file twice—use the “ignore duplicate” option or check the import’s duplicate detection.

For direct connections, issues often involve:

• Bank not listed in the provider’s supported institutions.
• Authentication failures due to two-factor authentication or bank security changes.
• Rate limits or API downtime on the provider side.

If you hit a wall, the Firefly III community forum and documentation are good places to search for solutions.

Costs and Privacy Considerations

Firefly III itself is free and open-source, but the import methods have different cost profiles. CSV import is completely free—you only need your bank statement file. Direct connections may involve costs: Spectre and Salt Edge offer free trials but then charge monthly fees based on the number of accounts or connections. Nordigen is free for personal use, but you must check its current terms. Privacy-wise, CSV import keeps your data on your own server, while direct connections share your transaction data with the provider (and possibly your bank’s API partner). If you are privacy-conscious, CSV is the safer choice.

Alternatives and Advanced Options

If neither method suits you, there are other ways to get data into Firefly III:

• Manual entry—tedious but always available.
• Using the Firefly III API to write your own import script (e.g., from a bank that offers its own API).
• Community tools that convert bank-specific formats to Firefly III-compatible files.

These require more technical skill but give you full control.

Frequently Asked Questions

Can I use both CSV import and a bank connection at the same time?
Yes, you can. The Data Importer supports multiple import configurations. You might use a direct connection for your main checking account and CSV for a credit card that the provider doesn’t support.

Which bank connection provider should I pick?
It depends on your bank. Check each provider’s coverage list first. Nordigen is popular because it’s free for personal use, but it may not support all banks. Spectre and Salt Edge have broader coverage but may cost money.

Is my bank data safe with a direct connection?
It is transmitted to the provider’s servers and stored according to their policies. You are trusting them with your transaction history. CSV import avoids that by keeping everything on your own server.

Can I automate CSV import?
Yes, if you are comfortable with scripting. You can write a script to download the CSV from your bank (if they offer a direct download link) and then use the Data Importer’s command-line interface to run the import. This is a common community approach.

Why does my CSV import show wrong amounts?
Usually it’s a mapping issue—check that the amount column is correctly identified and that the sign (positive/negative) is correct. Some banks use different conventions for debits and credits.

Do I need to install anything extra for CSV import?
Yes, the Firefly III Data Importer is a separate tool. It can be installed via Docker or as a standalone PHP application. The main Firefly III installation does not include the importer.

Related

• Retries, Timeouts, and Circuit Breakers: When to Use Each
• Clipboard Access Denied: Error Explained
• Cheap Mechanical Keyboards: What to Know Before Buying