beangulp

What it is

beangulp is the import framework of Beancount, the plain-text double-entry tool. Its README describes it as a framework for importing transactions into a Beancount ledger from account statements and other documents, and for managing those documents. It is the evolution of beancount.ingest from Beancount 2.3 and replaced it in Beancount 3.0 (released 2024-06-22). It is GPL-2.0 and written mainly by Martin Blais and Daniele Nicolodi.

How it works

You write one Python class per source. The Importer base class asks for two methods, identify(filepath) (is this file mine?) and account(filepath) (which account does it belong to?), and offers optional date, filename, extract, deduplicate and sort. A small script registers your importers with beangulp.Ingest, which gives you three commands:

• identify walks a downloads folder and says which importer claims each file.
• extract runs the importers and prints Beancount entries, in sections per source file. With --existing ledger.beancount it compares each new entry with existing ones dated within two days either side. The default comparator treats two transactions as the same if they share accounts and the amounts are within 5%. Likely duplicates get a __duplicate__ mark and are printed commented out, with a ; duplicate of file:line pointer.
• archive moves each original into a tree that mirrors the account name, renamed YYYY-MM-DD.name.

The package ships a CSV importer base and a file-only importer. Bank-specific importers live in users’ own repositories and community collections.

Data and access

Everything is local files. Input is whatever you downloaded; output is Beancount text and an archive folder. There is no server, no network access, no JSON output. The interface is documented in docstrings and an examples directory; the README points to the older beancount.ingest docs as partly relevant.

Agents

There are no agent features, but the shape suits agents. An importer is a small class with two required methods, so an agent can write one for a new bank export in minutes and test it with identify and extract. The review step is built in: extract produces candidate entries and a person merges them. Fava runs the same importers from its Import page, which gives that review a UI. Community MCP servers such as beanquery-mcp and beancount-mcp query the ledger afterwards; this pass found none that wraps beangulp itself.

Customers

Beancount users who write some Python. Signals on 2026-10-10: 145 stars and 43 contributors on GitHub, about 47,100 PyPI downloads in the last month according to pypistats (a count that includes mirrors and CI). Open issues ask for configurable CSV reading and better deduplication, and one asks how to install without new releases: the last tag is v0.2.0 (2025-01-20) while master changed until 2026-05-30.

History

The identify, extract and file workflow existed as beancount.ingest from 2016. beangulp was split out in February 2021, reached PyPI as v0.1.0 in May 2024, became the importer system for Beancount 3 in June 2024, and released v0.2.0 in January 2025. Fava 1.30 (December 2024) switched to beangulp for Beancount 3 and made deduplication an explicit hook; Fava 1.30.13 (May 2026) dropped Beancount 2, leaving beangulp as the only path.

For ownpurse

This is the closest prior art for ownpurse’s file connectors, and much of it should be copied: recognizing a file by content rather than by name, a stable archive name for the original, and duplicates marked with a pointer instead of silently dropped. Where ownpurse departs is in what happens next. beangulp’s output is text a person pastes in, and only the importer’s own choices link an entry back to its file. A fuzzy match is the only defence against importing twice. ownpurse stores the original by SHA-256 in the drawer, records facts with provenance, and treats a match between sources as a link rule with a confidence, so two witnesses to the same payment stay two facts rather than one being deleted.