> ## Documentation Index > Fetch the complete documentation index at: https://ngquct-fix-release-funnel-leaks.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Beancount > Open Beancount ledgers with TablePro 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, the remaining directives, metadata, 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: ```bash theme={null} pip3 install beancount ``` 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`: ```bash theme={null} rledger --version ``` To verify Python Beancount: ```bash theme={null} python3 -c "import beancount" ``` If TablePro cannot find a supported backend, set the executable path before launching the app: ```bash theme={null} launchctl setenv TABLEPRO_RUSTLEDGER_BINARY /opt/homebrew/bin/rledger launchctl setenv TABLEPRO_BEANCOUNT_PYTHON /opt/homebrew/bin/python3 ``` To force a backend: ```bash theme={null} launchctl setenv TABLEPRO_BEANCOUNT_BACKEND python ``` ## Connecting to a Beancount ledger Open TablePro and click **Create Connection...** or press **Cmd+N**. Choose **Beancount** from the database type list. Click **Browse...** and select a `.beancount` file. Click **Save & Connect** to open the ledger. Beancount ledger open in TablePro with projected tables in the sidebar Beancount ledger open in TablePro with projected tables in the sidebar ## Connection URL ```text theme={null} beancount:///path/to/main.beancount ``` See [Connection URL Reference](/databases/connection-urls) for all parameters. ## Tables | Table | Contents | | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | `transactions` | Transaction date, flag, payee, narration, and source location, including transactions with no postings | | `postings` | Posting account, amount, commodity, resolved cost basis (`cost_number`, `cost_currency`), and source location | | `accounts` | Opened accounts and declared currencies | | `prices` | Price directives | | `balances` | Computed account balances by commodity | | `balance_assertions` | Beancount balance directives | | `commodities` | Commodity directives | | `documents` | Document directives, their attached paths, tags, and links | | `notes` | Account notes | | `events` | Event type and description directives | | `closes` | Close directives | | `transaction_metadata` | Transaction metadata key/value pairs | | `posting_metadata` | Posting metadata key/value pairs | | `transaction_tags` | Transaction tags | | `transaction_links` | Transaction links | | `diagnostics` | Validation diagnostics from `rledger check` | | `source_files` | Parsed ledger and include files | Amounts come from whichever backend parsed the ledger, so thousands separators, arithmetic, cost (`{}`), and price (`@`/`@@`) annotations arrive already resolved to their booked values. Metadata values are projected as text. Booleans keep their Beancount spelling, `TRUE` and `FALSE`. ## Source locations `transactions` and `postings` carry `source_file`, `line`, and `source_location`. `source_location` is formatted as `path:line`, so it can be copied, filtered, or exported directly. A posting points at its own line rather than the line of the transaction that contains it. Valid transactions with no postings remain in `transactions` with their metadata, tags, links, and source location. A transaction the backend generates rather than reads, such as the one inserted for a `pad`, has whatever location that backend gives it. `rledger` leaves these columns empty; Python Beancount points them at the `pad` directive. ## Diagnostics The `diagnostics` table holds structured validation output: `source_file`, `line`, `source_location`, `column_number`, `end_line`, `end_column`, `severity`, `phase`, `code`, and `message`. The table is populated by `rledger check`. A ledger opened through `rledger` is projected even when it fails validation, so the entries the projection skipped are readable here rather than only on the command line. Ledgers opened on the Python Beancount backend leave the table empty. TablePro refreshes the projection when a referenced document file is created or removed, so document existence diagnostics stay current without editing the ledger. ## 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: ```sql theme={null} BQL: SELECT account FROM accounts ORDER BY account ``` 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. * `pad` directives are not projected as their own table. `rledger` does not expose the padded and source accounts, so the directive is only visible through the balancing transaction it inserts. The directive itself remains in the original source files. * The SQL projection covers common ledger directives; unsupported directives remain available in the original source files.