ANN: TurboBean – A Fast Beancount Implementation

[Moritz Drexl]

Hi all,

I'd like to share a project I'm working on: A from-scratch implementation of

Beancount that is fast and independent of the Python ecosystem.

https://github.com/themoritz/turbobean

Why?

I love Beancount, but as my journal has grown, processing takes a considerable
amount of time. I came across the Beancount Vnext: Goals & Design document
which talks about how to address this with re-implementing the core in C++. And
since Martin has so little time working on Beancount these days, I thought why
not work on this evolved version of Beancount myself? I added some of my own
design ideas to the mix and the result is TurboBean.

Philosophy

My vision is to have this very minimalist and fast core Beancount
implementation that is not tied to any language or ecosystem. It has some
essentials included (in particular the LSP) to get started quickly but then
mainly just interfaces with other languages via Protobuf.

- Single binary, zero dependencies. You download one small binary and it just
  works — no Python environment, no pip, no virtualenvs.
- Instant processing. Even large journals are parsed and processed in
  milliseconds.
- Plugins in Lua. Extend and customize processing without the overhead of
  a full Python runtime.
- Interop with other languages. Just use templating to generate .bean files.
  Pipe the output of processed transactions into any other language via
  Protobufs.
- LSP and formatter built in. Every editor gets first-class support out of the
  box — jump to account definitions, hover for balances, auto-completion and
  renaming for accounts/tags/links.
- Practical Web UI included. A built-in web server gives you basic journal,
  balance sheet, and income statement views to get started quickly. Similar to
  Fava.

Compatibility

TurboBean aims to be as compatible with existing .bean files as possible. Most
files should work without changes. Where breaking changes exist, they stem from
the redesigned booking system inspired by Vnext. The key changes are described
in this document.

Current Status

The project is at a point where I use the LSP for editing all my .bean files
and the Web UI for basic reports.

I plan to work next on Lua plugins, the formatter as well as Protobuf output.

The project is definitely still exploratory so it would be great to have people
play with it, and get feedback on design decisions since that's always the
toughest part.

Best,
Moritz

[Martin Blais]

Great work Moritz! Thank you for sharing it broadly :-)

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/beancount/a2b794df-0e57-4bbb-abe3-1df34db824e3n%40googlegroups.com.

[Timothy Jesionowski]

Hi Moritz, two thoughts. First of all, can I query the ledger using TurboBean? And second of all, how large are your ledgers that processing takes a lot of time? I have kept a fairly detailed ledger for three years and any processing takes less than a tenth of a second. 

Sincerely,

Timothy Jesionowski

[David Avraamides]

Hi Timothy,

As a data point, I have a ledger with 59k directives, 113k postings and 56k transactions covering a little over 13 years of data (I imported my history when I moved to Beancount a few years ago). If I delete my .picklecache file and start up bean-query (which processes my full ledger), it takes 3.1s on my M4 Pro Mac mini (48GB of memory). While 3 seconds doesn't sound like much, when you hit it over and over (say when doing EOM recs), it does add notable friction. If I'm doing read-only work where it can use the cache, it's better, but still 1.1s per invocation.

-David

[Moritz Drexl]

Hey Timothy,

It's mostly like David describes. While I don't have as many transactions as he has (only ~6 years worth of data), running a query still takes on the order of 1s on my M1 MacBook Air. It's not preventing me from maintaining my ledger but adds friction when iterating a lot (recs). I really enjoyed that instant feedback feeling when starting out with Beancount and no longer have it. And it's only going to get worse every year that my ledger grows. All the existing editor extensions and LSPs also call out to Python Beancount behind the scenes (afaik) so I also have the 1s delay for editor diagnostics. In Fava, the delay is a lot higher (~6s) for any change that I make to my .bean files to appear in the UI. I think it's because it's refreshing a lot of caches so that navigation between accounts doesn't take the full 1s every time.

Re querying the ledger, I'm still torn on whether that is something that belongs into the core. For now my thinking is that querying is a different component that just works off of the Protobuf output of the core. But on the other hand maybe that adds too much overhead, and the implementation requires too much knowledge of the Beancount internals (like booking) anyway? I haven't looked into it too closely yet and am open both ways. I'm also not sure what percentage of users rely on it out of the box. I for example use Fava most of the time and bean-query only once in a while for advanced stuff like when I do my taxes.

Happy to hear your thoughts!

Moritz

[Justus Pendleton]

Sounds like a fun project!

I tried it but nothing happened, unfortunately:

> ~/Downloads/turbobean-x86-linux-0.0.2/turbobean serve my.bean                                                                                                                                            ─╯
[error]: FileNotFound

> ~/Downloads/turbobean-x86-linux-0.0.2/turbobean -h                                                                                                                                                       ─╯
Turbobean is a fast Beancount implementation. (version 0.0.2)

[..... the rest cut....]

[redst...@gmail.com]

As another data point: I load only ~8 years of my ledger (~20k entries); anything more is unusably slow. Even this subset takes 3–4 seconds on an Intel Core Ultra 7 / 16 GB, making editing with Fava open quite frustrating.

A faster implementation without Python overhead would be a major improvement, and would also finally make running Beancount as an LSP during editing feasible.

[redst...@gmail.com]

Wow, very cool project. It’s impressively fast! It’s currently not usable for me due to the surrounding ecosystem and plugin support, but nevertheless, this is very promising!

I’m curious:

• Roughly how many hours did it take to go from zero to this state?
• I assume this was largely AI-assisted? If so, what inputs did you provide (current Beancount repo, v3 docs, design notes, etc.), and what was the AI technology used?
• How helpful was AI for the frontend work? Did you reference Fava in the process?

A few architectural questions:

• Why not expose a Python interface so existing plugins can be reused? In my experience, plugins don’t materially impact performance.
• Fava has accumulated a large feature set over many years. Would integrating with Fava be difficult? Given that it now makes fewer direct Beancount library calls, could this be handled by constructing the expected Python data structures instead of protobufs?
• Similarly for Beanquery: how complex would integration be, and what would the expected performance tradeoff look like?

​

[Stefano Zacchiroli]

On Mon, Feb 23, 2026 at 11:37:02PM -0800, 'Moritz Drexl' via Beancount wrote:
> I'd like to share a project I'm working on: A from-scratch implementation of
> Beancount that is fast and independent of the Python ecosystem.
>
> https://github.com/themoritz/turbobean

Thanks a lot for this.

> It has some essentials included (in particular the LSP) to get started
> quickly but then mainly just interfaces with other languages via
> Protobuf.

Can the LSP part be used independently from the rest? Like, as backend
for eglot in Emacs?

TIA,
Cheers
--
Stefano Zacchiroli - https://upsilon.cc/zack
Full professor of Computer Science, Polytechnic Institute of Paris
Co-founder & CSO Software Heritage

[Moritz Drexl]

Hi Stefano, yes, the LSP can be used independently form the rest and that's where I think the most value of the project is right now. The readme contains a minimal Emacs/eglot configuration that I managed to get working on my machine (though I'm not an Emacs user so feel free to improve it). Let me know how it goes!

[Moritz Drexl]

Hi, thanks for giving it a try! I am using a Mac myself so I tried reproducing your problem in a Ubuntu/Linux VM but it seems to be working fine. Are you sure that my.bean exists in your current working directory? TurboBean is always looking for files relative to the CWD. If it still doesn't work could you provide more details about your system, where my.bean, turbobean is located and what your CWD is?

[Moritz Drexl]

On Wednesday, February 25, 2026 at 4:19:43 PM UTC+13 redst...@gmail.com wrote:

Wow, very cool project. It’s impressively fast! It’s currently not usable for me due to the surrounding ecosystem and plugin support, but nevertheless, this is very promising!

I’m curious:

• Roughly how many hours did it take to go from zero to this state?
• I assume this was largely AI-assisted? If so, what inputs did you provide (current Beancount repo, v3 docs, design notes, etc.), and what was the AI technology used?
• How helpful was AI for the frontend work? Did you reference Fava in the process?

A few architectural questions:

• Why not expose a Python interface so existing plugins can be reused? In my experience, plugins don’t materially impact performance.
• Fava has accumulated a large feature set over many years. Would integrating with Fava be difficult? Given that it now makes fewer direct Beancount library calls, could this be handled by constructing the expected Python data structures instead of protobufs?
• Similarly for Beanquery: how complex would integration be, and what would the expected performance tradeoff look like?
  
  

Thanks for the feedback and questions!

I worked on this for about 9 months on and off in my spare time (mostly while waiting until the kids fall asleep). It's hard to tell how many hours went into it.

I started without using AI but am ramping up recently as the models get much better. I mostly do the research about the existing Beancount myself (reading codebase, v3 docs and design notes) and also write the core processing logic myself. Very good for learning all the details of Beancount! I mostly use AI to do research outside of Beancount, and to write the frontend part (most notably D3js), though I didn't reference Fava. More recently I'm more heavily experimenting with Claude and Amp to let the AI do bigger code changes.

Regarding Python, I'm aware that many users will probably miss using the existing plugins, but I've been hesitant to introduce the dependency on Python. Lua on the other side can just be embedded into the binary. I might experiment with maybe having something like an optional Python dependency for people who really want to use the Python plugins, and then use Lua as a fallback?

Regarding integrating Fava and Beanquery I'd need to study their codebases to get a good understanding of how easy it is to integrate them (and this is getting a lot easier now with AI's help). My gut feeling is that it should be possible to just let them use a different backend. But the amout of effort will depend on how cleanly the code interface to Beancount is in these projects. Definitely something that's in the back of my mind, especially for Fava, since it'll be hard to replicate the large feature set and that's something I don't see as part of the scope of TurboBean.

Moritz

[Justus Pendleton]

On Thursday, February 26, 2026 at 8:46:12 AM UTC+10:30 moritz...@googlemail.com wrote:

Hi, thanks for giving it a try! I am using a Mac myself so I tried reproducing your problem in a Ubuntu/Linux VM but it seems to be working fine. Are you sure that my.bean exists in your current working directory? TurboBean is always looking for files relative to the CWD. If it still doesn't work could you provide more details about your system, where my.bean, turbobean is located and what your CWD is?

Yep, pretty sure :-)

I've since tried it again and the problem is turbobean doesn't fully understand beancount's include syntax, so it fails to load my bean file. In an ideal world the error message would have been clearer (perhaps a line number where the error occurred?) but I realise this is version 0.2 of a personal project.

beancount allows globs in the include and turbobean doesn't, e.g.

include "archived/*.bean"

Admittedly a quick scan of beancount documentation doesn't seem to spell this out but loader_test.py has explicit tests to ensure it works (test_glob_relative, test_glob_relative_abs, test_glob_relative_mixed).