ledgerkit

A deterministic, Python-native accounting and query engine with a documented hledger-compatible foundation. ledgerkit uses hledger as its primary accounting and compatibility reference — it implements most important hledger functionality and preserves compatibility where it's useful, but it does not aim to be a line-for-line Python clone. Where Python or modern tooling offers a materially better design, ledgerkit says so explicitly rather than copying a limitation for its own sake. See dev-docs/compat-register/ for the machine-readable record of exactly which behaviours match hledger, which are deliberate extensions, and which are documented, intentional divergences.

• Parse .journal files compatible with the hledger 1.52 format
• Comprehensive directive support: include, account, commodity, payee, alias, P, Y, D, apply account
• Core CLI commands: balance, register, print, accounts, stats, check
• Strict mode (-s) and balance assertions
• Multi-commodity balances with tree rollup
• Commodity display style inference and -c override flag
• Optional pandas DataFrame export (pip install ledgerkit[pandas])
• Editor-integration layer: lenient parser, round-trip writer, EditorDocument
• Pure Python — no third-party runtime dependencies
• Python 3.8–3.12

• Python 3.8+

pip install ledgerkit

With optional pandas support:

pip install ledgerkit[pandas]

git clone https://github.com/ctosullivan/ledgerkit.git
cd ledgerkit
pip install -e ".[pandas]"

ledgerkit balance myfile.journal
ledgerkit register myfile.journal
ledgerkit accounts myfile.journal
ledgerkit print myfile.journal
ledgerkit stats myfile.journal

You can also invoke ledgerkit as a Python module:

python -m ledgerkit balance myfile.journal

import ledgerkit

journal = ledgerkit.load("myfile.journal")
accounts = journal.accounts()
balance  = journal.balance()

See docs/python-api.md for the full library reference.

Install the optional pandas extra for DataFrame export:

pip install ledgerkit[pandas]

Then:

import ledgerkit

journal = ledgerkit.load("myfile.journal")

# Export all postings to a DataFrame
df = journal.to_dataframe()
print(df.groupby("account")["amount"].sum())

# Or export directly from a report object
balance_df = journal.balance().to_dataframe()
register_df = journal.register().to_dataframe()
accounts_df = journal.accounts().to_dataframe()

# Run all tests
python -m unittest discover -s tests -t . -v

See dev-docs/architecture.md for module design and dev-docs/api-spec.md for the full API specification.

See dev-docs/hledger-compatibility.md for which hledger journal features are supported in v1.

See CONTRIBUTING.md for pull request guidelines, commit message format, and branch naming. This project follows the Contributor Code of Conduct.

Clone the full repository including AI-workflow files:

git clone https://github.com/ctosullivan/ledgerkit.git

Use sparse checkout to clone only the source code, tests, and human docs (excludes CLAUDE.md, dev-docs/, CHANGELOG.md, ROADMAP.md):

git clone --filter=blob:none --sparse https://github.com/ctosullivan/ledgerkit.git
cd ledgerkit
git sparse-checkout set ledgerkit tests docs README.md LICENSE pyproject.toml

ledgerkit is a Python implementation inspired by two pioneering plain-text accounting projects. We gratefully acknowledge their authors and contributors.

John Wiegley created Ledger, the original plain-text double-entry accounting tool, which established the journal file format and accounting model that this ecosystem is built upon.

https://github.com/ledger/ledger

Simon Michael created hledger, a Haskell implementation of Ledger's concepts, which has since evolved its own rich feature set and extensive documentation. ledgerkit's journal format and query-language support is modelled primarily on the hledger 1.52 specification, and ledgerkit is licensed under the same licence family as hledger (GPL-3.0-or-later) specifically so that hledger's own documentation, source, and test suite can be used directly — with provenance recorded — to understand and verify intended behaviour. See dev-docs/planning/core-redefinition/10-source-assisted-development.md for exactly what that does and doesn't mean in practice.

https://github.com/simonmichael/hledger

A full list of hledger contributors can be found at:

https://github.com/simonmichael/hledger/blob/main/doc/CREDITS.md

Their work — and the broader plain-text accounting community — makes ledgerkit possible.

ledgerkit is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later) — see LICENSE and NOTICE. This matches hledger's own licence exactly (also GPL-3.0-or-later), which is deliberate: see dev-docs/planning/core-redefinition/02-licence-migration.md for why. Released versions before this change (0.1.0 through 1.0.0, and the 1.0.0.dev1 pre-release) remain available under the MIT License they were originally published under — this is not retroactive.