Firefly-YNAB4-Importer 0.3

Firefly iii Importer from YNAB 4

Simple importer for moving from YNAB4 (You Need A Budget) to Firefly-iii.

What?

This tool lets you migrate your financial history from YNAB 4 (not nYNAB) to Firefly-iii with minimal manual actions. It’s written in Python and has the following features:

• Create asset accounts, budgets, budget history, categories, revenue accounts, expense accounts.

• Import splits accurately!

• Automatically verifies the integrity of import by comparing Running Balance in YNAB 4 to Firefly iii

• Foreign currency support - convert to foreign amounts in Firefly-iii seamlessly. Also gets real amounts from memo if that’s part of your YNAB workflow.

• Idempotent imports! Ran into an error mid-import? Just run it again after correcting the problem.

• Handle inactive budgets

• Caches firefly data so re-runs are fast

These cases are unsupported / not on the roadmap:

• Importing budget limits - YNAB 4’s secret sauce is the rules. One of those rules - live on last month’s income doesn’t match how Firefly budgets things. So this will require some more thought / investigation on how to set up sanely.

• Multiple foreign currencies (rare, but possible)

Why?

YNAB 4 is (was?) a desktop software with support for sharing using external mechanisms like Dropbox or just local file sharing like Airdrop. After version 4, YNAB went online with monthly subscription, all data on the cloud and stopped supporting YNAB 4. If you don’t like your financial data on the cloud, very few alternatives exist, and Firefly is one of the solid ones.

Firefly iii gives you control over where you want to host the application - local / in your own cloud etc, provides most of the features that YNAB 4 did and then some. Reports in particular are :100:.

However, if you have historical data in YNAB 4 like I do, starting fresh means throwing away all that history. Firefly iii does support migration from nYNAB (the cloud version) natively, but not from YNAB 4. There’s also a csv importer but it misses a lot of things that this tool fixes, such as:

1. Doesn’t import budget history.

2. Need manual management of accounts (otherwise it gets confused about “Citi” the asset account with “Citi” the expense account).

3. Transfers get duplicated because YNAB stores them as two transactions.

4. Splits are a whole can of worms.

5. No support for foreign transactions

6. Flaky import - doesn’t really work for imports of more than 500 transactions at a time and fails intermittently.

How?

Pre-requisites:

1. Python 3.8+

Setup:

1. Install: pip install Firefly-YNAB4-Importer

2. Export YNAB 4 data to local disk

3. Setup config (see config.example.toml for documentation)

4. Backup Firefly iii database! (IMPORTANT!)

   • Either using Firefly iii export, or just backing up your SQL database.

5. Run import:

   export FIREFLY_III_URL=<firefly url>
   export FIREFLY_III_ACCESS_TOKEN=<firefly access token>
   firefly-ynab4-importer import <config file> "<register path>" "<budget path>"

   where:

   • <firefly url> is the url for your firefly installation

   • <firefly access token> is the personal access token for your user

   • <config file> is the path to config file created earlier

   • <register path> is the path to the YNAB export register file (the one named

     <budge name> as of <timestamp>-Register.csv)

   • <budget path> is the path to the YNAB export budget file (the one

     named <budge name> as of <timestamp>-Budget.csv).

   • Remember to double quote since that path contains spaces.

6. Additional options:

   • Limit imports to certain dates (this is useful in verifying that import works fine for your use case)

     firefly-ynab4-importer import <config file> "<register path>" "<budget path>" "<start month>" "<end month>"

Development

Setup:

1. Install python 3.8+ using favorite tool e.g. Pyenv.

2. Optionally create virtualenv using your favorite method e.g. Pyenv virtualenv.

3. Install requirements: pip install -e .[dev]

4. Verify Firefly-YNAB4-Importer runs cleanly.

5. Publish new version:

   python setup.py sdist bdist_wheel
   
   twine upload dist/*

Bugs

We use GitHub issues for tracking bugs and feature requests. YNAB 4 and Firefly iii are both fairly complicated software. It’s not only possible, but likely that you’ll run into issues if your setup is moderate to high level of customization.

If you find a bug, please open an issue.

Contributing

If you find this useful and want to contribute, here’s a list of feature I’d like to add -

• Import Reconciliation transactions correctly

• Investigate budget history support

• Multiple foreign currencies (rare, but possible)

• Command to clear cache, and move cache to appropriate directory depending on platform (e.g. ~/.cache on Unix)

• Better error handling - guide user on how to correct problems

• Testing

  • Set up test fixtures for inputs and expected outputs

  • Verify all the options in Config work correctly

• Type checking - mypy checks.