Firefly III — Self-Hosted Personal Finance Manager

What Firefly III Does

• Transaction Tracking: Record expenses, income, and transfers between accounts
• Budgeting: Set monthly/weekly budgets per category and track spending progress
• Account Management: Multiple bank accounts, credit cards, savings, and cash wallets
• Multi-Currency: Full multi-currency support with automatic exchange rates
• Bank Import: Import transactions from CSV, OFX, QIF, CAMT.053, and via Spectre/GoCardless
• Categories & Tags: Organize transactions with categories, tags, and custom groups
• Rules Engine: Auto-categorize, auto-tag, and auto-process transactions based on rules
• Reports: Spending reports, income vs expense, net worth, budget performance
• Recurring Transactions: Automatic creation of recurring bills and income
• Piggy Banks: Virtual savings goals with progress tracking
• Bills: Track recurring expenses and see upcoming payments

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Web UI      │────▶│  Firefly III │────▶│  MySQL /     │
│  (Blade/JS)  │     │  (Laravel)   │     │  PostgreSQL /│
└──────────────┘     └──────────────┘     │  SQLite      │
                                          └──────────────┘

Self-Hosting

Docker Compose

services:
  firefly:
    image: fireflyiii/core:latest
    ports:
      - "8080:8080"
    environment:
      APP_KEY: your-32-character-app-key-here!
      DB_CONNECTION: pgsql
      DB_HOST: db
      DB_PORT: 5432
      DB_DATABASE: firefly
      DB_USERNAME: firefly
      DB_PASSWORD: firefly
      TZ: Asia/Shanghai
      DEFAULT_LANGUAGE: zh_CN
      DEFAULT_LOCALE: equal
    depends_on:
      - db
    volumes:
      - firefly-upload:/var/www/html/storage/upload

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: firefly
      POSTGRES_PASSWORD: firefly
      POSTGRES_DB: firefly
    volumes:
      - pg-data:/var/lib/postgresql/data

  # Optional: automated bank import
  importer:
    image: fireflyiii/data-importer:latest
    ports:
      - "8081:8080"
    environment:
      FIREFLY_III_URL: http://firefly:8080
      FIREFLY_III_ACCESS_TOKEN: your-personal-access-token

volumes:
  firefly-upload:
  pg-data:

Key Features

Transaction Types

Withdrawal:  💸 Spending money (expenses)
Deposit:     💰 Receiving money (income)
Transfer:    🔄 Moving between own accounts

Example:
├── Withdrawal: Grocery store → $85.50 (Category: Food)
├── Withdrawal: Netflix → $15.99 (Category: Entertainment)
├── Deposit: Salary → $5,000 (Category: Income)
└── Transfer: Checking → Savings → $500

Budget System

Monthly Budget: $3,000
├── Food & Groceries: $600 [$420 spent, $180 remaining]
│   ██████████████░░░░░░ 70%
├── Transportation: $200 [$180 spent, $20 remaining]
│   ██████████████████░░ 90%
├── Entertainment: $150 [$75 spent, $75 remaining]
│   ██████████░░░░░░░░░░ 50%
└── Utilities: $300 [$285 spent, $15 remaining]
    ███████████████████░ 95%

Automation Rules

Rule: "Auto-tag grocery purchases"
  When: Description contains "Walmart" OR "Costco" OR "Whole Foods"
  Then:
    → Set category to "Groceries"
    → Add tag "Supermarket"
    → Set budget to "Food"

Rule: "Flag large purchases"
  When: Amount > $500
  Then:
    → Add tag "Large Purchase"
    → Add note "Review this transaction"

Reports

Available reports:

• Budget: Monthly budget performance with overspend alerts
• Category: Spending breakdown by category with trends
• Tag: Tag-based analysis and comparison
• Net Worth: Assets minus liabilities over time
• Income vs Expense: Monthly comparison chart
• Audit: Transaction audit log per account

API

# List transactions
curl http://localhost:8080/api/v1/transactions 
  -H "Authorization: Bearer YOUR_TOKEN"

# Create transaction
curl -X POST http://localhost:8080/api/v1/transactions 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"transactions": [{"type": "withdrawal", "date": "2024-04-10", "amount": "25.50", "description": "Coffee shop", "source_id": "1", "category_name": "Food"}]}'

Firefly III vs Alternatives

FAQ

Q: Should I pick Firefly III or Actual Budget? A: Firefly III focuses on comprehensive transaction records and report analysis — ideal for users who want to track every inflow and outflow in detail. Actual Budget centers on envelope budgeting — ideal for users who want strict budget control. Pick Firefly III for bookkeeping, Actual Budget for budgeting.

Q: Does it support a Chinese UI? A: Yes. Set DEFAULT_LANGUAGE=zh_CN for a Simplified Chinese interface. All reports and UI elements are fully translated.

Q: Can I automatically import bank transactions? A: The Data Importer tool can connect to the Nordigen (GoCardless) API to auto-import transactions from European and US banks. For Chinese banks you need to manually export CSV and import. You can also write custom import scripts via the API.

Sources & Credits

• GitHub: firefly-iii/firefly-iii — 22.9K+ ⭐ | AGPL-3.0
• Website: firefly-iii.org