hledger-textual
A full-featured terminal user interface for hledger plain-text accounting. Manage transactions, recurring rules, budgets, and investments — with multi-period reports, account drill-downs, and git sync — all from your terminal.
Built with Textual and Python.
Stack
- Python 3.12+
- Textual - TUI framework
- hledger - plain-text accounting (must be installed separately)
- uv - package manager (no
requirements.txtneeded, dependencies are inpyproject.toml) - pytest - testing
Requirements
- Python 3.12+
- hledger installed and available in
PATH
Installation
# With pipx
pipx install hledger-textual
# With uv
uv tool install hledger-textual
Usage
hledger-textual -f path/to/your.journal
The journal file is resolved in this order:
-f/--fileCLI argumentLEDGER_FILEenvironment variable~/.config/hledger-textual/config.toml(journal_filekey)~/.hledger.journal
Default currency
For multi-currency journals, the default currency is resolved in this order:
- The first
commoditydirective declared in the journal (followingincludefiles), e.g.commodity €1,000.00. - The
default_commoditykey in~/.config/hledger-textual/config.toml.
When resolved, the Accounts and Summary views convert balances to that
currency using hledger -X --infer-market-prices, so P price directives in
the journal are honored (see examples/multicurrency-prices.journal).
Commodities without a price are shown in their original currency, and the
Summary's Income / Expenses / Liabilities breakdowns show — instead of a
percentage for them (a note names the excluded commodities). Percentages are
always computed on converted amounts, so rows in different currencies are
never compared one-to-one.
When nothing is resolved, the Accounts view shows each account's balances in
their original currencies (stacked within the cell), the Reports view's flat
multi-period mode marks multi-currency accounts with a ◆ prefix, and the
Summary overview shows a per-currency balance line under each card (marquee
scrolling when it overflows). The Reports view's stacked mode (M) always
expands each currency into its own row. Summary breakdown percentages stay
hidden (—) for journals that mix currencies in that case, since there is no
common denominator; single-currency journals are unaffected.
To pin a currency via config instead:
default_commodity = "€"
Documentation
See the Wiki for the full documentation: feature overview, configuration, investment tracking, and per-tab reference.
Development
git clone https://github.com/thesmokinator/hledger-textual.git
cd hledger-textual
uv sync
Testing
# Run all tests
uv run pytest
# Run with verbose output
uv run pytest -v
# Run with coverage report
uv run pytest --cov=hledger_textual --cov-report=term-missing
1 maintainer
Metadata
1 maintainer
Release files for hledger-textual 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hledger_textual-0.5.0.tar.gz | 150.0 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hledger_textual-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 342.9 kB
Release files / hledger_textual-0.5.0.tar.gz
| Download URL | hledger_textual-0.5.0.tar.gz |
|---|---|
| Size | 150.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d2a0af15a4d0933e7147a7237bfda147ed33b1d1ee20cf0945e58be76fce56f
|
|
BLAKE2b-256 checksum How to use checksums |
7f37c4f3f5891dd1743493bd620f305058f42b5bbcafa95f9721360e63590f83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / hledger_textual-0.5.0-py3-none-any.whl
| Download URL | hledger_textual-0.5.0-py3-none-any.whl |
|---|---|
| Size | 192.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69c2efdfe69765ac6d6a31e91cd0f9493bea2ec42280a9910a37bca683f267bf
|
|
BLAKE2b-256 checksum How to use checksums |
8b3b872be090339a279ccbbe55554a489b58efcc085170ee0660262a41dc1495
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for hledger-textual 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for hledger_textual-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
