gnucash2firefly/README.md

GnuCash to Firefly III Migration Tool

This tool helps you migrate your financial data from GnuCash to Firefly III automatically using the piecash library for robust GnuCash file parsing.

What it does

• Connects to your GnuCash SQLite database using piecash library for reliable parsing
• Creates corresponding accounts in Firefly III with proper hierarchical names and account types
• Migrates transactions between accounts with dates, amounts, and descriptions
• Handles multiple currencies by enabling them in Firefly III first
• Provides safety features like test limits and accounts-only migration

What gets migrated

Accounts

• All account types (assets, liabilities, expenses, income) with proper type mapping
• Full hierarchical account names (e.g., "Assets:Current Assets:Checking Account")
• Account descriptions and account numbers
• Currency information
• Placeholder accounts are skipped as they're organizational only

Transactions

• Simple 2-split transactions with dates, amounts, descriptions
• Transaction memos/notes
• Multi-currency support
• Complex split transactions are logged but skipped for manual review

Requirements

pip install -r requirements.txt

Or manually:

pip install requests python-dateutil piecash

Setup

1. Get your Firefly III API token

   • Log into your Firefly III instance
   • Go to Options → Profile → OAuth → Personal Access Tokens
   • Create a new token and copy it

2. Set your API token (choose one method):

   Option A: Environment variable

   export FIREFLY_TOKEN="your_actual_token_here"
   

   Option B: Command line argument

   python g2f.py --firefly-token "your_actual_token_here" [other options]
   

3. Export your GnuCash data to SQLite format

   • In GnuCash: File → Export → Export Accounts
   • Choose SQLite format and save the .gnucash file

Usage

Migrate accounts only (useful for initial setup):

python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com" \
  --accounts-only

Test with a few transactions:

python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com" \
  --test-limit 5

Full migration:

python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com"

Command Line Options

• --gnucash-db - Path to your GnuCash SQLite database file (required)
• --firefly-url - Your Firefly III base URL (required)
• --firefly-token - API token (optional if using FIREFLY_TOKEN environment variable)
• --test-limit - Limit number of transactions for testing (optional)
• --accounts-only - Only migrate accounts, skip transactions

Safety Features

• Test limits: Use --test-limit to migrate only a few transactions first
• Accounts-only mode: Use --accounts-only to set up account structure first
• Detailed logging: All actions are logged with timestamps
• Error handling: Failed operations are logged and don't stop the entire migration
• Hierarchical account names: Full GnuCash account paths preserve your organization

Account Type Mapping

GnuCash types are mapped to Firefly III types as follows:

GnuCash Type	Firefly III Type
ASSET, BANK, CASH, CHECKING, SAVINGS, INVESTMENT, STOCK	asset
LIABILITY, CREDIT, CREDITCARD, LOAN	liability
EXPENSE	expense
INCOME	revenue
EQUITY, RECEIVABLE	asset
PAYABLE	liability

Account Hierarchy

GnuCash's hierarchical account structure is preserved by using full account paths as names in Firefly III:

• GnuCash: Assets → Current Assets → Checking Account
• Firefly III: Assets:Current Assets:Checking Account

This maintains your account organization while working within Firefly III's flat account structure.

Important Notes

• Always backup your Firefly III data before running a migration
• Test with accounts-only first using --accounts-only to verify account structure
• Then test with a small subset using --test-limit
• Complex transactions (more than 2 splits) are logged but not migrated - review these manually
• Placeholder accounts are skipped as they're organizational only

Troubleshooting

1. "Failed to connect to GnuCash database"

   • Make sure the file path is correct
   • Ensure the file is in SQLite format (exported from GnuCash)
   • Check that piecash can read your GnuCash version

2. "Failed to connect to Firefly III"

   • Check your Firefly III URL is correct and accessible
   • Verify your API token is valid
   • Ensure FIREFLY_TOKEN environment variable is set or use --firefly-token

3. "Missing account mapping for transaction"

   • Some accounts may have failed to create in Firefly III
   • Check the logs for account creation errors
   • Run with --accounts-only first to debug account issues

Example Output

2024-01-01 10:00:00 - INFO - Connected to GnuCash database: data.gnucash
2024-01-01 10:00:01 - INFO - Successfully connected to Firefly III API
2024-01-01 10:00:02 - INFO - Found 45 accounts in GnuCash
2024-01-01 10:00:03 - INFO - Enabled currency: USD
2024-01-01 10:00:04 - INFO - Created account: Assets:Current Assets:Checking Account -> 123
2024-01-01 10:00:05 - INFO - Successfully created 42 accounts
2024-01-01 10:00:06 - INFO - Found 1250 transactions in GnuCash
2024-01-01 10:00:15 - INFO - Successfully created 1180 out of 1250 transactions
2024-01-01 10:00:15 - INFO - Migration completed! Migrated 42 accounts and 1180 transactions

Migration Workflow

1. Create accounts: python g2f.py --gnucash-db file.gnucash --firefly-url URL --accounts-only
2. Migrate sample: python g2f.py --gnucash-db file.gnucash --firefly-url URL --test-limit 10
3. Full migration: python g2f.py --gnucash-db file.gnucash --firefly-url URL