firefly-reports

CI PyPI CodeQL Coverage License: GPL v3 Python 3.11+

Generate 26 financial reports (PDF + Excel) from a Firefly III instance. Designed for individuals, freelancers and small businesses who want a complete annual financial overview.

Quick start

pip install firefly-iii-reports

firefly-reports \
  --url https://your-firefly-instance.example.com \
  --year 2025 \
  --owner "Your Name" --out ./output

To run from source instead, clone the repo and use python -m firefly_reports.main in place of firefly-reports (dependencies: pip install -r firefly_reports/requirements.txt).

Use --year YYYY for a full calendar year (all reports), or --start/--end for a custom date range — in date-range mode the year-only reports (YoY, Historical Growth, Liquidity Forecast) are skipped.

The token can be provided via --token, the FIREFLY_TOKEN environment variable, a .env file, a firefly-reports.toml config file, or an interactive prompt.

Reports generated

Standard (always generated)

# Report Description
1 Cash Flow Statement Income/expense by category with monthly breakdown
2 Income vs Expense Summary with savings rate and budget breakdown
3 Transaction Register Chronological list with running balance
4 Net Worth Assets grouped by account type
5 Account Statements Per-account transaction statement
6 Tax Summary Cash-basis income and deductible expenses
7 Expense Trend Category × month expense matrix
8 Tagged Report Transactions filtered by tag (--tags)
9 Budget vs Actual Planned vs real spend with pace status
10 Bills & Subscriptions Recurring payments with status
11 Savings Goals Piggy bank progress
12 Liabilities Debt summary with period movement
13 KPI Scorecard Burn rate, cash runway, savings rate, HHI
14 Year-over-Year Income and expense comparison vs prior year (--year mode only)
15 Cumulative Cash Flow Monthly cumulative series
16 Income by Client Income breakdown per client (revenue source)

Strategic (non-legacy mode)

# Report Description
18 Budget Performance Forecast Month-end projection from current velocity
19 Category Ledger Transactions grouped by category
20 Payee Ledger Transactions grouped by payee
21 Linkage & Reimbursement Report Linked pairs with link type and linked-amount %
22 All Tags Ledger Transactions grouped by tag (--all-tags)
23 Historical Growth Multi-year income/expense comparison (--years, --year mode only)
24 Liquidity Forecast 6-month projected balance (--year mode only)
25 General Journal Chronological double-entry register with protocol numbers and daily totals (Libro Giornale)
26 Summary Firefly instance info (version, API, OS, PHP, user), global counts and period statistics

Report 17 — Transaction Audit Log (audit_log_<period>.pdf) is now generated only when --legacy-report is active. The Summary report takes its slot in standard mode.

Demo (no Firefly III required)

python -m firefly_reports.demo --out ./output --year 2025 --lang en

Config file

firefly-reports init     # interactive wizard — creates firefly-reports.toml

Documentation

Full documentation is on the GitHub Wiki:

Development

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v

See CONTRIBUTING.md and the Developer Guide on the wiki.

License

GPL v3 — see LICENSE.

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bytesdust from gravatar.com bytesdust

Credits

Author: fran33git

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GPL-3.0-or-later

Requires

Python >=3.11

Provides Extra

dev

Tags

firefly-iii finance reports pdf excel accounting

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

firefly_iii_reports-1.0.1.tar.gz (109.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

firefly_iii_reports-1.0.1-py3-none-any.whl (100.5 kB view details)

Uploaded Python 3

File details

Details for the file firefly_iii_reports-1.0.1.tar.gz.

File metadata

  • Download URL: firefly_iii_reports-1.0.1.tar.gz
  • Upload date:
  • Size: 109.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for firefly_iii_reports-1.0.1.tar.gz
Algorithm Hash digest
SHA256 4cd7e8b3610d86d742d9e6ed5995be655d5eb3ac1cc83889a41315546cb36fce
MD5 175cb69b2414f9d0e73fe031d1e75585
BLAKE2b-256 d27ef85d92fec069aac6f2ce6f5045fd94be859908907b44ea7bc85f035a0bf4

See more details on using hashes here.

Provenance

The following attestation bundles were made for firefly_iii_reports-1.0.1.tar.gz:

Publisher: release.yml on fran33git/firefly-reports

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file firefly_iii_reports-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for firefly_iii_reports-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 b789455fc4bf1b9e10237ce93ca5f6b1b77e645c56f1aa800fd76607b81e3dee
MD5 03e6c57f44f8908cabb064c30f961c03
BLAKE2b-256 6286ee449197f49f429ed4ce3b295251fe86ec0947f5422402e8e5f4465b9a6c

See more details on using hashes here.

Provenance

The following attestation bundles were made for firefly_iii_reports-1.0.1-py3-none-any.whl:

Publisher: release.yml on fran33git/firefly-reports

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page