Skip to main content
TablePro opens .beancount ledgers as read-only, file-based connections. If the Beancount plugin is not installed yet, TablePro prompts you to download it before opening the ledger. The driver projects transactions, postings, accounts, prices, computed balances, balance assertions, and source files into SQL tables for browsing and exports. The plugin uses either rledger (the rustledger project) or Python Beancount to parse ledgers. TablePro does not bundle either one, so install one yourself before opening a ledger. When both are available, TablePro uses rledger; Python Beancount is the fallback for browsing projected SQL tables. The plugin also supports BQL queries through rledger. BQL requires the rledger executable even when the ledger was opened through Python Beancount.

​
Backend requirements

Install the Python backend with pip:
For rledger, build or download the rustledger project and put the executable on PATH, in /opt/homebrew/bin, or in /usr/local/bin. TablePro then discovers backends in this order:
  1. rledger from TABLEPRO_RUSTLEDGER_BINARY, then PATH, then /opt/homebrew/bin and /usr/local/bin.
  2. A python3 that can import beancount, from TABLEPRO_BEANCOUNT_PYTHON, then PATH, then /opt/homebrew/bin/python3, /usr/local/bin/python3, and /usr/bin/python3.
The names are exact: an executable called rledger, and a python3 that imports beancount. Any other Beancount-compatible parser has to be installed under one of those names, or pointed at with the environment variables below. To verify rledger:
To verify Python Beancount:
If TablePro cannot find a supported backend, set the executable path before launching the app:
To force a backend:

​
Connecting to a Beancount ledger

1

Create a new connection

Open TablePro and click Create Connection… or press Cmd+N.
2

Select Beancount

Choose Beancount from the database type list.
3

Choose your ledger file

Click Browse… and select a .beancount file.
4

Connect

Click Save & Connect to open the ledger.
Beancount ledger open in TablePro with projected tables in the sidebar

A Beancount ledger projected into SQL tables

​
Connection URL

See Connection URL Reference for all parameters.

​
Tables

Amounts come from whichever backend parsed the ledger, so thousands separators, arithmetic, cost ({}), and price (@/@@) annotations arrive already resolved to their booked values.

​
Includes

The parser follows Beancount include directives. Literal includes and glob patterns such as include "imports/*.beancount" and include "imports/**/*.beancount" are supported.

​
BQL

Prefix a query with BQL: to run it through your configured rledger executable:
Table browsing, row counts, and pagination work for BQL results. BQL queries do not support SQL parameters.

​
Troubleshooting

Beancount needs rledger or Python Beancount: No backend was found. An app launched from Finder does not inherit your shell’s PATH, so rledger --version working in Terminal is not enough. Set TABLEPRO_RUSTLEDGER_BINARY or TABLEPRO_BEANCOUNT_PYTHON with launchctl setenv, then relaunch TablePro. TABLEPRO_BEANCOUNT_PYTHON points to a Python executable that cannot import beancount: Run pip3 install beancount with that exact interpreter, or point the variable at one that already has the package. BQL queries need rledger: BQL always runs through rledger, even when the ledger opened on the Python backend. Install rledger, or drop the BQL: prefix and query the projected tables instead. File does not exist: The ledger moved or was renamed. Re-pick it with Browse… in the connection form. Beancount include cycle detected: Two ledger files include each other. Break the loop in the source files.

​
Limitations

  • Beancount connections are read-only.
  • Schema editing, imports, SSH, SSL, and database switching are not available for ledgers.
  • The SQL projection covers common ledger directives; unsupported directives remain available in the original source files.