21 posts tagged with "Beancount"

We're excited to announce the launch of Beancount.io's completely revamped website! After months of careful development and feedback from our amazing community, we've created a more intuitive, comprehensive, and resourceful hub for all your plain-text accounting needs.

A Fresh New Look​

Our rebranded homepage reflects our commitment to clarity and simplicity—the very principles that make plain-text accounting so powerful. With a clean, modern design that emphasizes usability, we've made it easier than ever to find exactly what you need. The new visual identity better represents our mission: making accounting accessible and transparent for everyone from hobbyists to financial professionals.

Expanded Documentation & Tutorials​

We've significantly expanded our documentation and tutorial sections to support users at every level:

• Getting Started Guide: A completely revamped onboarding experience for newcomers to plain-text accounting
• Interactive Tutorials: Step-by-step walkthroughs with real-world examples
• Advanced Topics: Detailed documentation on complex accounting scenarios, customizations, and integrations
• Command Reference: Comprehensive explanations of every command and option within Beancount
• Troubleshooting: Common issues and their solutions, contributed by our community experts

Each tutorial has been carefully crafted to take you from concept to implementation with practical examples you can apply to your own books immediately.

Resources for Better Accounting​

Beyond just explaining how to use Beancount, we've added resources to help you become better at accounting itself:

• Accounting Principles Library: Learn fundamental concepts like double-entry bookkeeping, accrual vs. cash accounting, and proper categorization
• Financial Reporting Templates: Ready-to-use templates for common reports like income statements, balance sheets, and cash flow statements
• Tax Preparation Guides: Country-specific resources to help with year-end tax preparation using Beancount data
• Industry-Specific Setups: Example configurations for freelancers, small businesses, and personal finance
• Community Showcase: Real-world examples (with sensitive data removed) showing how others organize their accounting systems

What's Next?​

This website refresh is just the beginning. We're committed to continually improving the Beancount experience based on your feedback. Coming soon:

• Additional integration tutorials for popular financial services
• Renovate beancount mobile apps
• More localized content for international users
• Expanded community forum for knowledge sharing
• Regular webinars on advanced accounting topics

We'd love to hear what you think about the new site! Share your feedback through our community channel.

Happy accounting!

The Beancount.io Team

Core Functionality and Philosophy of Beancount​

Beancount is an open-source, double-entry accounting system that uses plain text files to record transactions. At its core, Beancount treats your ledger as a dataset defined by a simple, strict grammar. Every financial event (transactions, account openings, commodity prices, etc.) is a directive in a text file, which Beancount parses into an in-memory database of entries. This design enforces the double-entry principle: every transaction must balance debits and credits across accounts. The result is a highly transparent and auditable ledger that you can version-control, inspect, and query with ease.

Philosophy – correctness and minimalism: Beancount’s design prioritizes data integrity and simplicity. Its creator, Martin Blais, describes Beancount as “pessimistic” in assuming the user will make mistakes and thus imposes extra checks and constraints. For example, Beancount will not allow you to remove assets that were never added (preventing negative stock holdings or cash balances) and can enforce that every account is opened before use. It lacks Ledger’s concept of “virtual” or automatically balanced postings – an intentional choice to force fully balanced entries. Beancount effectively “goes hardcore” on correctness with more cross-checks than basic double-entry provides. This cautious approach appeals to users who “do not trust themselves too much” and want the software to catch their errors.

Minimal options, maximum consistency: In contrast to Ledger’s myriad of command-line flags and tuning options, Beancount opts for minimalism. There are very few global options, and none that change transaction semantics outside the ledger file. All configuration that affects accounting (like commodity cost basis methods or booking assumptions) is done in-file via directives or plugins, ensuring that loading the same file always produces the same results regardless of how reports are generated. This design avoids the complexity of Ledger’s many knobs and the subtle interactions between them. Beancount’s philosophy is that an accounting tool should be a stable, deterministic pipeline from input file to reports. It achieves this by treating the ledger as an ordered stream of directives that can be programmatically processed in sequence. Even things that Ledger treats as special syntax (like opening balances or price statements) are first-class directives in Beancount’s data model, which makes the system highly extensible.

Extensibility via plugins and query language: Beancount is implemented in Python and provides hooks to inject custom logic into the processing pipeline. Users can write plugins in Python that operate on the stream of transactions (for example, to enforce a custom rule or generate automatic entries). These plugins run as the file is processed, effectively extending Beancount’s core functionality without needing to modify the source. Beancount also includes a powerful query language (inspired by SQL) to slice and dice the ledger. The bean-query tool treats the parsed ledger as a database and lets you run analytical queries on it – for instance, summing expenses by category or extracting all transactions for a given payee. In Beancount 3.x, this querying capability was moved into a standalone beanquery package, but from a user perspective it still provides flexible reporting via SQL-like queries.

Plain text and version control: As a plaintext accounting tool, Beancount emphasizes user control and longevity of data. The ledger is simply a .beancount text file that you can edit in any text editor. This means your entire financial history is stored in a human-readable form, and you can put it in Git or another VCS to track changes over time. Users often keep their Beancount file under version control to maintain an audit trail of every edit (with commit messages describing changes). This approach aligns with Beancount’s philosophy that accounting data, especially personal or small-business finances, should be transparent and “future-proof” – not locked in a proprietary database. In Martin Blais’s own words, Beancount is a “labor of love” built to be simple, durable, and free for the community. It was first developed around 2007 and has evolved through major rewrites (v1 to v2, and now v3 in 2024) to refine its design while preserving its core philosophy of minimalism and correctness.

Tools, Plugins, and Extensions in the Beancount Ecosystem​

The Beancount ecosystem has grown a rich set of tools, plugins, and extensions that enhance the core ledger functionality. These cover importing data, editing ledgers, viewing reports, and adding specialized accounting features. Below is an overview of key components and add-ons in the Beancount world:

Data Importing Utilities (Importers)​

One of the most important needs for practical use is importing transactions from banks, credit cards, and other financial institutions. Beancount provides an import framework and community-contributed import scripts for this purpose. In Beancount 2.x, the built-in module beancount.ingest (with commands like bean-extract and bean-identify) was used to define importer plugins in Python and apply them to downloaded statements. In Beancount 3.x, this has been replaced by an external project called Beangulp. Beangulp is a dedicated importers framework that evolved from beancount.ingest and is now the recommended way to automate transaction import for Beancount 3.0. It allows writing Python scripts or command-line tools that read external files (like CSV or PDF statements) and output Beancount entries. This new approach decouples import logic from the Beancount core – for example, the old bean-extract command has been removed in v3, and instead your import scripts themselves produce transactions via Beangulp’s CLI interface.

Dozens of ready-made importers exist for different banks and formats, contributed by the community. There are importer scripts for institutions around the world – from Alipay and WeChat Pay in China, to various European banks (Commerzbank, ING, ABN AMRO, etc.), to US banks like Chase and Amex. Many of these are collected in public repositories (often on GitHub) or in packages like beancount-importers. For instance, the Tarioch Beancount Tools project (tariochbctools) provides importers for Swiss and UK banks and even handles crypto transaction imports. Another example is Lazy Beancount, which packages a set of common importers (for Wise, Monzo, Revolut, IBKR, etc.) and provides a Docker-based setup for easy automation. No matter which bank or financial service you use, chances are someone has written a Beancount importer for it – or you can write your own using Beangulp’s framework. The flexibility of Python means importers can handle parsing CSV/Excel files, OFX/QIF downloads, or even scraping APIs, then emit transactions in standardized Beancount format.

Editing and Editor Integration​

Because Beancount ledgers are just text, users often leverage their favorite text editors or IDEs to maintain them. The ecosystem provides editor support plugins to make this experience smoother. There are extensions for many popular editors that add syntax highlighting, auto-completion of account names, and real-time error checking:

• Emacs Beancount-Mode: An Emacs major mode (beancount-mode) is available to edit .beancount files, offering features like syntax coloring and integration with Beancount’s checker. It can even run bean-check in the background so that errors in the ledger (like an unbalanced transaction) are flagged as you edit.
• VS Code Extension: A Beancount extension on the VSCode Marketplace provides similar conveniences for Visual Studio Code users. It supports syntax highlighting, alignment of amounts, auto-completion for accounts/payees, and even on-the-fly balance checks when you save the file. It can also integrate with Fava, letting you launch the Fava web interface from within VSCode.
• Plugins or modes also exist for Vim, Atom, and other editors. For example, there’s a Tree-sitter grammar for Beancount, which powers syntax highlighting in modern editors and was even adopted in Fava’s web-based editor component. In short, whatever your editing environment, the community has likely provided a plugin to make editing Beancount files convenient and error-free.

For quick entry of transactions outside of traditional editors, there are also tools like Bean-add and mobile apps. Bean-add is a command-line tool that allows adding a new transaction via a prompt or one-liner, handling date and account suggestions. On mobile, a project called Beancount Mobile provides a simple interface to input transactions on the go (for example, recording a cash purchase from your phone). Additionally, a Beancount Telegram Bot exists to capture transactions through messaging – you can send a message with transaction details, and the bot formats it into your ledger file.

Web Frontends and Visualization Tools​

(Fava) Fava’s web interface provides an interactive dashboard for Beancount, featuring reports like an income statement with visualizations (shown here as a treemap of expenses by category) alongside tables of accounts and balances.

The flagship frontend for Beancount is Fava, a modern web interface. Fava runs as a local web app that reads your Beancount file and produces a rich interactive experience in your browser. It offers a full suite of reports: balance sheet, income statement, net worth over time, portfolio holdings, performance charts, budgets, and more – all out of the box. Users often cite Fava as a major reason for choosing Beancount over other plain-text accounting tools. With a single command (fava ledger.beancount), you can browse your finances with graphs and tables instead of text. Fava supports features like: drilling down on accounts, filtering transactions by payee or tag, a query editor (so you can run Beancount queries and see results in the browser), and even an integrated web-based editor for your ledger. It is highly usable, making plain text accounting approachable for those who prefer visual interfaces.

Under the hood, Fava is written in Python (Flask on the backend) and JavaScript (Svelte on the frontend). It has its own release cycle and is actively maintained. Notably, Fava has kept pace with Beancount’s development – for instance, Fava 1.30 added support for Beancount v3, switching to use the new beanquery and beangulp packages internally. (It still supports Beancount 2 for older ledgers.) Fava’s focus on usability includes nice touches like auto-complete in the web editor, and a sleek UI with dark mode and responsive charts. There’s also a spin-off called Fava-GTK, which packages Fava in a desktop application for GNOME/Linux users who prefer a native app feel.

Beyond Fava, other visualization and analysis options exist. Because Beancount data can be exported or queried as tables, users often leverage tools like Jupyter notebooks or Pandas for custom analysis. For example, one user describes pulling data from Beancount via the query interface into a Pandas DataFrame to prepare a custom report. There are also community-contributed scripts for specific reports – e.g. a portfolio allocation analysis tool or a process control chart for spending vs. net worth. However, for most people Fava provides more than enough reporting power without needing to write code. It even supports extensions: you can drop in Python files that add new report pages or charts to Fava. A notable extension is fava-envelope for envelope budgeting within Fava. Overall, Fava serves as the central visualization hub of the Beancount ecosystem.

Command-Line Utilities and Scripts​

Beancount comes with various CLI tools (especially in the older v2 branch, some of which were trimmed in v3). These tools operate on your ledger file to check it or generate specific reports in text or HTML:

• bean-check: a validator that checks for syntax errors or accounting errors in the file. Running bean-check myfile.beancount will alert you to any imbalance, missing account, or other issues, and output nothing if the file is error-free.
• bean-format: a formatter that tidies up your ledger by aligning numbers into neat columns, much like running a code formatter on source code. This helps keep the file clean and readable.
• bean-query: an interactive shell or batch tool to run Beancount’s query language on your ledger. You can use it to produce custom tabular reports (e.g., bean-query myfile.beancount "SELECT account, sum(amount) WHERE ...").
• bean-report: a versatile report generator (in v2) that can output predefined reports (balance sheet, income statement, trial balance, etc.) to the console or to files. For example, bean-report file.beancount balances would print account balances. (In practice, many of these text reports have been supplanted by Fava’s nicer presentation.)
• bean-web / bean-bake: an older web interface that would serve the reports on localhost or “bake” them as static HTML files. These were mostly used before Fava became popular; bean-web provided a basic web view of the same reports bean-report could generate. In Beancount 3, bean-web has been removed (since Fava is the recommended web frontend now, offering a superior experience).
• bean-example: a utility to generate an example ledger file (useful for newcomers to see a template of Beancount entries).
• bean-doctor: a debugging tool that can diagnose issues in your ledger or environment.

It’s worth noting that as of Beancount v3, many of these tools were moved out of the core project. The core Beancount package was streamlined, and tools like the query engine and importers were split into separate packages (beanquery, beangulp, etc.) for easier maintenance. For example, bean-query’s functionality is now provided by the beanquery tool which is installed separately. From a user perspective, the functionality remains available; it’s just been modularized. The Arch Linux community noted this change when updating Fava: the Fava package added dependencies on beanquery and beangulp to support Beancount 3.x. This modular approach also allows others in the community to contribute to these auxiliary tools more independently of Beancount’s release cycle.

Beancount Plugins and Extensions​

A standout strength of the Beancount ecosystem is the plugin system. By adding a plugin "module.name" line in your Beancount file, you can incorporate custom Python logic that runs during the ledger processing. The community has created many plugins to extend Beancount’s capabilities:

• Data quality and rules: Examples include beancount-balexpr which lets you assert equations involving multiple accounts (e.g., Asset A + Asset B = Liability X), and beancount-checkclosed which auto-inserts balance assertions when you close an account to ensure it nets to zero. There’s even a plugin to ensure transactions in the file are sorted by date (autobean.sorted) to catch out-of-order entries.
• Automation: The beancount-asset-transfer plugin can generate in-kind transfer entries between accounts (useful for moving stocks between brokers while preserving cost basis). Another, autobean.xcheck, cross-checks your Beancount ledger against external statements for discrepancies.
• Recurring transactions and budgets: The “repete” or interpolate plugin by Akuukis allows defining recurring transactions or spreading an annual expense over months. For budgeting, the fava-envelope extension (used via Fava) supports envelope budgeting methodology in plain text. There’s also MiniBudget by Frank Davies – a small standalone tool inspired by Beancount to help with budgeting for personal or small business use.
• Tax and reporting: Some plugins help with tax accounting, like one that classifies capital gains into short vs long-term automatically. Another (fincen_114 by Justus Pendleton) generates an FBAR report for US taxpayers with foreign accounts, illustrating how Beancount data can be leveraged for regulatory reporting.
• Community plugin repositories: There are curated plugin sets such as beancount-plugins (by Dave Stephens) focusing on things like depreciation entries, and beancount-plugins-zack (by Stefano Zacchiroli) which include assorted helpers like sorting directives.

In addition to plugins, other utility tools orbiting Beancount address specific needs. For example, beancount-black is an auto-formatter similar to the Black code formatter, but for Beancount ledger files. There’s a Beancount Bot (Telegram/Mattermost) for adding transactions via chat as mentioned, and an Alfred workflow for macOS to quickly append transactions to your file. A tool named Pinto offers a “supercharged” CLI with interactive entry (like an enhanced bean-add). For those migrating from other systems, converters exist (YNAB2Beancount, CSV2Beancount, GnuCash2Beancount, Ledger2Beancount) to help bring in data from elsewhere.

In summary, the Beancount ecosystem is quite extensive. Table 1 below lists some major tools and extensions with their roles:

Comparison with Ledger, hledger, and Similar Systems​

Beancount belongs to the family of plain text double-entry accounting tools, among which Ledger CLI (John Wiegley’s Ledger) and hledger are prominent. While all these systems share the core idea of plaintext ledger files and double-entry bookkeeping, they differ in syntax, philosophy, and ecosystem maturity. The following table highlights key differences between Beancount, Ledger, and hledger:

In summary, Beancount differentiates itself with its emphasis on strictness, plugin-based extensibility, and a user-friendly web interface. Ledger remains the classic, highly flexible tool favored by command-line purists and those who need ultimate speed (Ledger’s C++ engine is very fast on huge files). hledger provides a middle ground – much of Ledger’s functionality with a bit more structure and an officially supported (if simple) web UI. All three share the advantages of plain text accounting (auditability, Git versioning, plain data), but Beancount’s ecosystem (especially with Fava) has arguably made it more accessible to the average user in recent years. On the flip side, Ledger/hledger users sometimes prefer their relative simplicity in setup (no Python needed) and long-proven stability. Ultimately, choosing between them comes down to personal preference: those who value rigorous correctness and a rich ecosystem often lean toward Beancount, whereas those who want lean, terminal-focused tooling might stick with Ledger or hledger.

Usage Scenarios for Beancount​

Beancount is versatile enough to be used for personal finance tracking as well as (in some cases) small business accounting. Its core double-entry approach is the same in both scenarios, but the scale and specific practices can differ.

Personal Finance​

Many Beancount users employ it to manage their individual or household finances. A typical personal finance setup in Beancount might include accounts for checking and savings, credit cards, investments, loans, income categories (salary, interest, etc.), and expense categories (rent, groceries, entertainment, etc.). Users record day-to-day transactions either manually (entering receipts, bills, etc.) or by importing from bank statements using the importer tools discussed earlier. The benefits Beancount brings to personal finance include:

• Consolidation and Analysis: All your transactions can live in a single text file (or a set of files) that represents years of financial history. This makes it easy to analyze long-term trends. With Beancount’s query language or with Fava, you can answer questions like “How much did I spend on travel in the past 5 years?” or “What’s my average monthly grocery bill?” in seconds. One user noted that after switching to Beancount, “analysis of financial data (spending, giving, taxes, etc.) is trivial” either through Fava or by querying the data and using tools like Pandas. In essence, your ledger becomes a personal financial database you can query at will.
• Budgeting and Planning: While Beancount doesn’t force a budgeting system, you can implement one. Some users do envelope budgeting by creating budget accounts or using the fava-envelope plugin. Others simply use periodic reports to compare spending to targets. Because it’s plain text, integrating Beancount with external budgeting tools or spreadsheets is straightforward (exporting data or using CSV outputs from queries).
• Investments and Net Worth Tracking: Beancount excels at tracking investments thanks to its robust handling of cost bases and market prices. You can record buys/sells of stocks, crypto, etc., with cost details, and then use Prices directives to keep track of market value. Fava can show a net worth over time chart and portfolio breakdown by asset class. This is hugely useful for personal wealth management – you get insights similar to what commercial tools like Mint or Personal Capital provide, but fully under your control. Multi-currency handling is also built-in, so if you hold foreign currencies or crypto, Beancount can track those and convert for reporting.
• Reconciliation and Accuracy: Personal finance often involves reconciling with bank statements. With Beancount, one can regularly reconcile accounts by using balance assertions or the documents feature. For example, every month you might add a balance Assets:Bank:Checking <date> <balance> entry to confirm your ledger matches the bank’s statement at month-end. The bean-check tool (or Fava’s error display) will alert you if things don’t line up. One user mentions doing a monthly reconciliation of all accounts, which “helps catch any unusual activity” – a good personal finance hygiene practice that Beancount facilitates.
• Automation: Tech-savvy individuals have automated large parts of their personal finance workflow with Beancount. Using importers, cron jobs, and maybe a bit of Python, you can set up your system so that, for instance, every day your bank transactions are fetched (some use OFX or APIs) and appended to your Beancount file, categorized by rules. Over time, your ledger becomes mostly auto-updated, and you just review and tweak as needed. A community member on Hacker News shared that after 3 years, their Beancount books were “95% automatic”. This level of automation is possible because of Beancount’s plain text openness and scripting capabilities.

Personal finance users often choose Beancount over spreadsheets or apps because it gives them complete ownership of the data (no reliance on a cloud service that might shut down – a concern as Mint was discontinued, for example) and because the depth of insight is greater when you have all your data integrated. The learning curve is non-trivial – one must learn basic accounting and the Beancount syntax – but resources like the official documentation and community tutorials help newcomers get started. Once set up, many find that it brings peace of mind to have a clear, trustworthy picture of their finances at all times.

Small Business Accounting​

Using Beancount for a small business (or nonprofit, club, etc.) is less common than personal use, but it is certainly possible and some have done it successfully. Beancount’s double-entry framework is in fact the same system that underpins corporate accounting, just without some of the higher-level features that dedicated accounting software provides (like invoicing modules or payroll integrations). Here’s how Beancount can fit into a small business context:

• General Ledger and Financial Statements: A small business can treat the Beancount file as its general ledger. You would have asset accounts for bank accounts, accounts receivable, maybe inventory; liability accounts for credit cards, loans, accounts payable; equity for owner’s capital; income accounts for sales or services; and expense accounts for all business expenses. By maintaining this ledger, you can produce an Income Statement (Profit & Loss) and Balance Sheet at any time using Beancount’s reports or queries. In fact, Beancount’s built-in reports or Fava can generate a balance sheet and P&L in seconds that are perfectly in line with accounting principles. This can be sufficient for a small operation to assess profitability, financial position, and cash flow (with a bit of querying for cash flow, since direct cash flow statements aren’t built-in but can be derived).
• Invoices and A/R, A/P: Beancount does not have a built-in invoicing system; users would typically handle invoicing outside (e.g., create invoices in Word or an invoice app) and then record the results in Beancount. For example, when you issue an invoice, you’d record an entry debiting Accounts Receivable and crediting Income. When the payment comes, you debit Cash/Bank and credit Accounts Receivable. This way, you can keep track of outstanding receivables by looking at the balance of the A/R account. The same applies to bills (A/P). While it’s more manual than specialized accounting software (which might send reminders or integrate with emails), it is perfectly doable. Some users have shared templates or workflows on how they manage invoices with Beancount and ensure they don’t miss open invoices (for instance, by using metadata or custom queries to list unpaid invoices).
• Inventory or Cost of Goods Sold: For businesses selling products, Beancount can track inventory purchases and sales, but it requires disciplined entries. You might use the Inventory and cost accounting features: purchasing inventory increases an asset account (with cost attached to the items), selling it moves cost to an expense (COGS) and records revenue. Because Beancount insists on matching lots, it will enforce proper reduction of inventory with the correct cost, which can actually ensure your gross profit calculations are accurate if done right. However, there’s no automated SKU tracking or anything – it’s all at the financial level (quantity and cost).
• Payroll and Complex Transactions: Beancount can record payroll transactions (salary expense, tax withholdings, etc.), but calculating those figures might be done externally or via another tool, then just booked into Beancount. For a very small business (say one or two employees), this is manageable. You’d, for example, record a single journal entry per pay period that splits out wages, tax withheld, employer tax expense, cash paid, etc. Doing this manually is similar to how one might do it in QuickBooks journal entries – it requires knowledge of what accounts to hit.
• Multi-user and Audit: One challenge in a business setting is if multiple people need to access the books or if an accountant needs to review them. Since Beancount is a text file, it’s not multi-user in real-time. However, hosting the file in a Git repository can enable collaboration: each person can edit and commit, and differences can be merged. A service like BeanHub (mentioned earlier) actually aims to facilitate this by providing a cloud platform on top of Git and Beancount – effectively simulating a multi-user accounting system with audit trails (every change is a Git commit). For audit purposes, the fact that every entry is timestamped and version-controlled can be a plus: you have an auditable trace of all changes. But traditional accountants might not be familiar with Beancount, so exporting to formats like CSV or even QuickBooks format might be needed if handing off to a CPA (some users export their trial balance to Excel for an accountant).
• Regulatory compliance: For tax filing or compliance, Beancount’s data can be used to generate the necessary reports, but it may require custom queries or plugins. We saw an example of a community plugin for Indian government compliance reporting, and one for FinCEN FBAR reporting. This shows that, with effort, Beancount can be adapted to meet specific reporting requirements. Small businesses in jurisdictions with simple requirements (cash accounting, or basic accrual) can certainly maintain books in Beancount and produce financial statements for tax returns. However, features like depreciation schedules or amortization might need you to write your own entries or use a plugin (Dave Stephens’ depreciation plugins help automate that for instance). There isn’t a GUI to “click depreciate asset” as in some accounting software; you’d encode the depreciation as transactions (which in a way demystifies it – everything is an entry you can inspect).

In practice, many tech-oriented small business owners have used Beancount (or Ledger/hledger) if they prefer control and transparency over the convenience of QuickBooks. A Reddit discussion noted that for standard small-business accounting with a limited volume of transactions, Beancount works fine. The limiting factor is usually the comfort level – whether the business owner (or their accountant) is comfortable with a text-based tool. One advantage is cost: Beancount is free, whereas accounting software can be costly for a small business. On the other hand, lack of official support and the DIY nature means it’s best suited for those who are both the business owner and somewhat technically inclined. For freelancers or sole proprietors with programming skills, Beancount can be an attractive choice to manage finances without relying on cloud accounting services.

Hybrid approaches are also possible: some small businesses use an official system for invoices or payroll, but periodically import the data into Beancount for analysis and archival. This way they get the best of both worlds – compliance and ease for day-to-day operations, plus the power of Beancount for consolidated insight. The growing ecosystem (like BeanHub’s forms for repetitive entries or direct bank integration via APIs) suggests that using Beancount for business might become easier over time. New tools aim to automate routine bookkeeping tasks (e.g., BeanHub can import bank transactions automatically and even has a concept of custom data entry forms for frequent transactions like monthly bills). These developments blur the line between personal and small-business use cases, potentially bringing plain-text accounting to a wider range of organizations.

In summary, Beancount can handle small business accounting, provided the user is willing to manually manage things that commercial software automates. It ensures a high degree of transparency – you deeply understand your books because you’re writing them – and for a diligent user, it can produce impeccable books. Both personal and business users benefit from Beancount’s core strengths: a reliable accounting engine, complete audit trail, and flexibility to adapt to unique scenarios (via scripting and plugins). Whether it’s tracking a household budget or a startup’s finances, Beancount offers a toolkit to do it with precision and openness.

Community and Development Activity​

Beancount has a dedicated community and a development story that reflects its open-source, niche-but-passionate nature. Below are key points about its community, maintainers, and related projects:

• Project Maintenance: Beancount’s primary author is Martin Blais, who began the project around 2007 and has shepherded it through multiple versions. Development for a long time was largely a one-man effort (aside from community contributions of patches). Martin’s philosophy was to build an accounting tool “useful to me first, as well as for others, in the simplest, most durable manner”. This personal motivation kept the project going as a labor of love. As of 2025, Martin Blais is still the lead maintainer (his name appears on commits and he answers questions on the mailing list/issue tracker), but the ecosystem around Beancount has many other contributors in their respective projects.

• GitHub and Repositories: The source code is hosted on GitHub under the beancount/beancount repository. The project is GPL-2.0 licensed and has attracted a modest number of contributors over the years. In mid-2024, Beancount Version 3 was officially released as the new stable branch. This release involved splitting out some components: for example, the beangulp repo (for importers) and beanquery repo (for the query tool) are part of the beancount GitHub organization now, maintained somewhat independently. The main Beancount repo focuses on the core accounting engine and file parser. As of 2025, Beancount’s GitHub shows active issue discussions and some ongoing development – though not high volume, issues and pull requests trickle in, and occasional updates are made to fix bugs or refine features.

• Fava Development: Fava, the web interface, started as a separate project (created by Dominic Aumayr, who copyrighted it in 2016). It has its own community of contributors and is also on GitHub under beancount/fava. Fava’s maintainers and contributors (e.g. Jakob Schnetz, Stefan Otte, and others in recent years) have been actively improving the interface, with releases every few months. Fava’s Gitter chat (linked on the Fava docs) and GitHub issue tracker are places where users and devs discuss new features or bugs. The project welcomes contributions, evidenced by a CHANGELOG note thanking multiple community members for their PRs. Fava’s close alignment with Beancount’s development (such as quickly adding support for Beancount v3 and new beanquery syntax) indicates good collaboration between the two projects.

• Mailing Lists and Forums: Beancount has an official mailing list (previously on Google Groups, titled “Beancount” or sometimes discussed on the general Ledger list). This mailing list is a treasure trove of knowledge – users ask questions about how to model certain scenarios, report bugs, and share tips. Martin Blais is known to respond on the mailing list with detailed explanations. In addition, the broader Plain Text Accounting community overlaps heavily. The Ledger CLI mailing list often entertains questions about Beancount as well, and there is a forum at plaintextaccounting.org and a subreddit r/plaintextaccounting where Beancount topics come up frequently. Users on these platforms discuss comparisons, share personal setups, and help newcomers. The general tone of the community is very cooperative – Beancount users often help Ledger users and vice versa, recognizing that all these tools have similar goals.

• Chat Groups: Besides mailing lists, there are chat channels like the Plaintext Accounting Slack/Discord (community-organized) and the Fava Gitter. These are less formal, more real-time ways to get help or discuss features. For example, one might hop on the Slack to ask if anyone has an importer for a specific bank. There is also a Matrix/IRC channel (historically #ledger or #beancount on IRC) where some long-time users idle. While not as populous as communities for mainstream software, these channels have knowledgeable folks who can often answer obscure accounting questions.

• Contributors and Key Community Members: A few names stand out in the Beancount community:

  • “Redstreet” (Red S): A prolific contributor who has written many plugins (like beancount-balexpr, sellgains, and others) and often provides support. They also maintain a set of importer scripts and a tool called bean-download to fetch statements.
  • Vasily M (Evernight): Author of some importer frameworks and plugins like beancount-valuation, and contributions to Fava regarding investments.
  • Stefano Zacchiroli (zack): A Debian developer who created the beancount-mode for Emacs and his own plugin repo. He has advocated for plaintext accounting in academic settings as well.
  • Simon Michael: While primarily the lead of hledger, he runs plaintextaccounting.org which includes Beancount. This cross-pollination helped bring Beancount to the attention of Ledger/hledger users.
  • Frank hell (Tarioch): Contributor of the Tarioch Beancount Tools, a major set of importers and price fetchers especially for European institutions.
  • Siddhant Goel: A community member who blogs about Beancount (for example, his guide on migrating to v3) and maintains some importers. His blog posts have helped many new users.

  These and many others contribute code, documentation, and help on forums, making the ecosystem vibrant despite its relatively small size.

• GitHub Stats and Forks: Beancount’s GitHub repo has accumulated a few hundred stars (indicating interest) and forks. Notable forks of Beancount itself are rare – there isn’t a well-known divergent fork that tries to be “Beancount but with feature X”. Instead, when users wanted something different, they either wrote a plugin or used another tool (like hledger) rather than fork Beancount. One could consider hledger a kind of fork of Ledger (not Beancount) and Beancount itself an independent re-imagining of Ledger’s ideas, but within Beancount’s repo there aren’t big splinter projects. The community has generally coalesced around the main repo and extended it via the plugin interface instead of fragmenting the codebase. This is likely because Martin Blais was open to external contributions (his docs even have a section acknowledging external contributions and modules) and the plugin architecture made it unnecessary to maintain a fork for most new features.

• Community Resources: There are several high-quality resources for learning and using Beancount created by the community:

  • The Beancount documentation on GitHub Pages (and the source Google Docs that Martin maintains) – very comprehensive, including theory on accounting and how Beancount implements it.
  • Beanhub Academy (academy.beanhub.io) – tutorials and articles (like “Beancount and double-entry accounting”) to teach concepts. This likely comes from the BeanHub project and helps new users get onboarded.
  • Numerous blog posts and personal notes – e.g., LWN.net had an article “Counting beans… with Beancount”, and many personal blogs (as listed in Awesome Beancount’s “Blog Posts” section) share experiences and tips. These help build knowledge and attract new users.
  • Talks and presentations: Beancount has been presented at meetups and conferences (for instance, a PyMunich 2018 talk on managing finances with Python/Beancount). Such talks introduce the tool to broader audiences and often spark interest on forums like Hacker News.

• Notable Related Projects: Apart from Fava, some other projects related to Beancount have their own communities:

  • BeanHub (mentioned earlier) – a newer entrant aiming to offer Beancount as a service with collaboration features. It’s a commercial venture but based on open-source underpinnings. BeanHub’s development shows an interesting model: a company building user-friendly layers over Beancount (they maintain GitHub repos like beanhub-cli, beanhub-import, etc.). This could bring more users who don’t want to maintain the environment themselves.
  • Plain Text Accounting site – maintained by Simon Michael, it aggregates info on all such tools and has a forum where people share usage for various tools including Beancount.
  • Financial tooling integration: Some users integrate Beancount with business intelligence tools or databases. For example, one Google Groups thread details using PostgreSQL with Beancount data via custom functions. While not mainstream, it shows the community’s experimental spirit in pushing Beancount’s capabilities (e.g., to handle very large datasets or complex queries beyond the built-in).

In summary, Beancount’s community, while smaller than those of big open-source projects, is highly engaged and knowledgeable. The project enjoys a steady stream of improvements and very helpful support channels. The collaborative ethos (sharing importers, writing plugins, answering questions) means that a newcomer in 2025 can rely on extensive prior work and community wisdom to set up their accounting system. Development is active in the ecosystem sense – Fava releases, plugin development, etc. – even if the core’s changes are more occasional. The ecosystem’s growth (as evidenced by the Awesome Beancount list of dozens of tools) speaks to a healthy community making Beancount ever more capable.

Recent Developments and Upcoming Features​

As of 2025, the Beancount ecosystem has seen significant developments in the past couple of years, and there are ongoing discussions about future enhancements. Here are some noteworthy recent developments and a glimpse of what might be coming:

• Beancount 3.0 Release (2024): After a long period of Beancount 2.x being the standard, version 3 was officially released in mid-2024. This was a major milestone because v3 represents a simplification and modernization of the codebase. Martin Blais had envisioned v3 as a chance to “rearrange and simplify” the system further. While it was originally thought to be a big rewrite, in practice the update for users was not too disruptive. The main changes were under the hood: a new parser, some performance improvements, and the extraction of optional components out of the core. The release was rolled out gradually (v3 had been in beta since 2022, but by July 2024 it became the recommended stable version). Users like Siddhant Goel reported that migrating from 2.x to 3.x was “mostly uneventful” with only a few workflow changes.

• Modularization – tools moved to separate packages: One of the big changes with Beancount 3 is that many tools that used to live in the monolithic repository were spun off. For example, bean-query is now provided by the beanquery package, and beancount.ingest was replaced by the beangulp package. Commands like bean-extract and bean-identify (for imports) were removed from core Beancount. Instead, the philosophy is to use standalone scripts for importing. This means that if you upgrade to v3, you’d install beangulp and run importer scripts (each importer is basically a small program) rather than having a central bean-extract config file. Similarly, queries are executed via beanquery which can be installed and updated independently of Beancount core. This modular approach was designed to make maintenance easier and encourage community contributions. It also slimmed down Beancount’s core, so the core focuses purely on parsing and accounting logic, while ancillary functionality can evolve separately. From a user perspective, after upgrading, one has to adjust commands (e.g., use bean-query from beanquery, or use Fava which abstracts this anyway). Fava’s changelog explicitly notes these changes: Fava now depends on beanquery and beangulp, and it handles import workflows differently for Beancount 3 vs 2.

• Performance Improvements: Performance was one motivation for revisiting Beancount’s design. The v3 plan (as outlined in Martin’s “V3 goals” document) included optimizing the parser and possibly making the loading process faster and less memory-intensive. By 2025, some of these improvements have materialized. Anecdotally, users with very large ledgers (tens of thousands of transactions, or lots of stock trades) have reported better performance with the latest version. For instance, a user dealing with “microinvestment transactions” who faced performance issues noted these concerns on the Google Group – this kind of feedback likely informed v3. The new parser is more efficient and written in a clearer way, which could be extended in the future. Additionally, Fava 1.29 moved to a more efficient file-watching mechanism (using the watchfiles library) to improve responsiveness when the ledger changes. Looking forward, the community might explore incremental parsing (only re-processing changed parts of the file instead of everything) to handle large ledgers more quickly – this was hinted in the docs as “Beancount server / incremental booking” idea.

• Investment Tracking Enhancements: There’s been ongoing work to make investment and portfolio reporting better. For example, handling of average cost basis vs. FIFO was discussed at length. While Beancount enforces lot matching, some users prefer average cost for certain jurisdictions. A proposal and discussion exist about making cost basis booking more flexible (possibly via a plugin or option). By 2025, no built-in switch for average cost is present, but the groundwork in v3 (the booking redesign) makes it easier for plugins to implement. A community plugin “Gains Minimizer” was released that can suggest which lots to sell to minimize taxes, showing the kind of advanced tooling being built around investments. Fava, too, added features like a portfolio summary extension (with rate of return calculations). In terms of upcoming features, one can expect more in this domain: possibly automated portfolio rebalancing suggestions or risk analysis, likely as external tools that read Beancount data (since the data is all there).

• New Plugins and Extensions: The plugin ecosystem continuously grows. Recent notable additions include:

  • Budget reporting tools – e.g., a simple CLI budget reporter if one doesn’t use Fava’s UI.
  • Encryption and security – the fava-encrypt setup, allowing Fava to be hosted online with the ledger encrypted at rest, was introduced, addressing the concern of self-hosting your finances.
  • Quality-of-life plugins – like autobean-format (a new formatter that can handle more corner cases by parsing and reprinting the file), and beancheck integration in editors (flymake for Emacs).
  • As financial needs evolve (for instance, people dealing in cryptocurrencies/NFTs, etc.), plugins have appeared to support those (e.g., handling of crypto price feeds, or custom commodities like NFTs via BeanHub).

  Looking ahead, the community is likely to continue filling gaps via plugins. For example, we might see more tax-related plugins (some users have shared scripts for things like computing wash sales or specific local tax reports).

• BeanHub and Commercial Ecosystem Growth: A recent development is the emergence of commercial services built on Beancount. BeanHub (launched around 2023) is one such service that indicates a trend: making Beancount more accessible to non-technical users by providing a friendly SaaS with automation. While not an open-source development per se, it leverages the Beancount engine and could drive features that eventually feed back into the open-source world. For instance, BeanHub’s need for direct bank integration (they mention “Direct Connect” for pulling bank CSVs) could result in improved import scripts or even new standards for import config. If BeanHub or others succeed, we might see Beancount gaining traction in small businesses who wouldn’t normally adopt a text-based tool. This could broaden the community and spur further development and funding.

• Potential Upcoming Features: Based on discussions on the issue tracker and mailing list, a few ideas are on the horizon (though not guaranteed):

  • Time Resolution: Currently, Beancount only tracks dates (no timestamps) for transactions. There have been questions about adding time (for stock trades or ordering of same-day transactions). Martin Blais explicitly decided that sub-day timestamps were out of scope to keep things simple. This is unlikely to change soon – so upcoming versions probably will not add time resolution, sticking to the stance that if you need time, you incorporate it into narration or an account.
  • Enhanced GUI editing: Fava is continuously improving its editing capabilities. A possibility is a more full-featured web editor (with auto-suggest, maybe a form-based entry for new transactions). The groundwork using tree-sitter in Fava’s editor was laid. We might see Fava become not just a viewer but a more powerful editor, reducing the need to open a text editor at all for many tasks.
  • Better multi-ledger support: Some users maintain multiple Beancount files (for different entities or for splitting personal vs business). Right now, including files is possible but had limitations (plugins in included files, etc.). A recent plugin autobean.include was created to safely include external ledgers. In the future, we might see first-class support for multi-file setups – perhaps a concept of a Beancount “project” with multiple files (this is hinted by features like the VSCode extension’s beancount.mainBeanFile setting). This would help those running multi-entity bookkeeping or wanting to modularize their ledger.
  • Realtime or Incremental Computation: As ledgers grow, the ability to recompute reports quickly becomes important. There is an idea of a Beancount server that stays running and updates results as transactions change. This could manifest as an optimization in Fava or a daemon that editor plugins can query. Perhaps a future Fava release will leverage a continuously running Beancount process to make the UI more responsive for huge ledgers.
  • Fund Accounting / Non-profit features: There was an enhancement proposal about fund accounting in Beancount. Non-profit organizations have accounting needs (restricted vs unrestricted funds) that could potentially be modeled with Beancount’s tag or account hierarchy. The discussion didn’t yet lead to built-in features, but if more non-profits pick up Beancount, this could drive new capabilities (maybe just documented best practices or plugins for fund balance tracking).

• Long-Term Outlook: Martin Blais hinted that he sees the future of Beancount in making the core more of an engine and moving more functionality to plugins. This is consistent with what we see (modularization in v3). So, an “upcoming feature” in philosophical terms is greater extensibility – possibly even allowing plugins to define new directive types or extend syntax in controlled ways. If that happens, Beancount’s core might remain relatively small and stable, while the ecosystem delivers most new functionality as add-ons. This could lead to a plugin marketplace or more centralized listing of plugins so users can pick and choose (the Awesome Beancount list is a start at that).

In conclusion, the Beancount ecosystem in 2025 is active and evolving. The release of Beancount 3.0 was a major recent event, ensuring the project’s foundation is solid for the future. Improvements in performance, tooling, and usability (especially via Fava) have continued to lower the barrier to entry. While Beancount remains a tool that requires some expertise, it is far more approachable now than a few years ago, thanks to these developments. Upcoming features will likely focus on refining the experience – faster performance, better integrations, and specialized extensions – rather than drastic changes to the core philosophy. The community’s trajectory suggests that Beancount will continue to mature as the centerpiece of plain text accounting, striking a balance between the austere power of double-entry bookkeeping and the convenience of modern software. As one user quipped on Hacker News, plain text accounting gives you “super powers” in understanding your finances – and Beancount’s recent and future improvements aim to make those super powers easier to wield for everyone.

Sources: Beancount documentation and repository; Fava documentation; “A Comparison of Beancount and Ledger” by Martin Blais; Awesome Beancount resource list; User experiences and community reports; BeanHub information; and various discussions on mailing lists and forums.

In the labyrinth of personal finance management, Beancount emerges as a beacon of clarity and precision for plain-text bookkeeping. Particularly when it comes to managing receivables—money expected from others—Beancount offers a structured approach to keep your financial records in impeccable order. This blog will guide you through the intricacies of tracking receivables, processing refunds, and managing unresolved transactions with Beancount. Whether you're returning a purchase, lending money, or awaiting a refund, this post is your roadmap to financial clarity.

Understanding Receivables in Beancount:​

Receivables represent money that is owed to you. This could be from a variety of scenarios, such as after a shopping return awaiting a refund or when you lend money to someone. For instance, consider you've returned a watch strap to an online store like Amazon.com and are awaiting a refund. In Beancount, this transaction is recorded as money moving from your credit card liability to your assets as receivables:

2023-10-31 * "Amazon.com" "[Return] Watch Strap"
    Liabilities:CreditCard:Chase                                 -12.00 USD
    Assets:Receivables

Managing Refunds:​

Once the refund is processed and you receive the money, another transaction is recorded to offset the balance in Receivables. This ensures that your accounts reflect the money back in your possession:

2023-11-01 * "Amazon.com" "[Refund] Watch Strap"
    Liabilities:CreditCard:Chase                                  12.00 USD
    Assets:Receivables

Complete Transaction Cycle:​

A complete in-and-out transaction involving receivables is combining both transactions above and showcased as follows, demonstrating a balanced account post-refund:

2023-10-31 * "Amazon.com" "[Return] Watch Strap"
    Liabilities:CreditCard:Chase                                 -12.00 USD
    Assets:Receivables

2023-11-01 * "Amazon.com" "[Refund] Watch Strap"
    Liabilities:CreditCard:Chase                                  12.00 USD
    Assets:Receivables

Handling Unresolved Transactions:​

For transactions where the refund or repayment has not yet been received, Beancount employs the #UNRESOLVED tag. This tag helps in identifying and tracking amounts that are still pending. For example:

2023-10-31 * "John Doe" "Lending Money" #UNRESOLVED
    Liabilities:CreditCard:Chase                                 -100.00 USD
    Assets:Receivables

By focusing on transactions tagged as #UNRESOLVED, you can quickly ascertain which amounts are yet to be settled.

Maintaining a Zero Balance:​

In a proper ledger, the sum of all transactions under the Assets:Receivables account, excluding those tagged with #UNRESOLVED, should ideally return to zero. This ensures that all expected funds have been accounted for, maintaining the integrity of your financial records.

For example, a valid ledger might look like this, with an unresolved transaction clearly marked, awaiting closure:

2023-10-31 * "Amazon.com" "[Return] Watch Strap"
    Liabilities:CreditCard:Chase                                 -12.00 USD
    Assets:Receivables

2023-11-01 * "Amazon.com" "[Refund] Watch Strap"
    Liabilities:CreditCard:Chase                                  12.00 USD
    Assets:Receivables

2023-10-31 * "John Doe" "Lending Money" #UNRESOLVED
    Liabilities:CreditCard:Chase                                 -100.00 USD
    Assets:Receivables

An invalid ledger is one where a transaction causes the Receivables account not to zero out, necessitating the #UNRESOLVED tag for correction.

Conclusion​

Navigating receivables in Beancount doesn't have to be daunting. With a clear understanding of how to record transactions, manage refunds, and keep an eye on unresolved transactions, you can maintain accurate and reliable financial records. Embracing the structured approach of Beancount for receivables management not only simplifies your financial tracking but also brings peace of mind, knowing that every dime is accounted for. So, why not leverage the power of Beancount to make your financial management as smooth

Real estate transactions may constitute the largest financial activity in a family's lifetime. This article explains how to model real estate in Beancount. I treat real estate as an asset and the appreciation of the house as unrealized gain. Additionally, the mortgage is modeled as a liability, and the interest is considered an expense.

Let's assume that Mr. A purchased a luxury home located at 123 ABC Street, XYZ City, CA, 12345 on January 1, 2020, for a price of 1 million. The interest rate is 3.0%, the down payment is 20%, and the loan amount is 800,000.

Create Accounts​

Firstly, we treat the house as an Asset. Since the house is being listed as an Asset, it needs to be given a unit. In this case, the unit quantity is only one, it's unlikely there will be multiple, and even if it's the nth house, we would want to record it in a separate Asset. That is to say, one house corresponds to one Asset, and this Asset has a special unit, its value can only possibly be 1.

2019-12-31 commodity HOUSE.ABC
  name: "123 ABC Street, XYZ City, CA, 12345"

2019-12-31 open Assets:Property:US:CA:123ABC                        HOUSE.ABC
2019-12-31 open Liabilities:Bank:US:SomeBank:Mortgage:Loan          USD

In the first line here, we defined a commodity unit representing the house. In the fourth line, we defined an Asset account, which holds the commodity unit previously defined as the house. In the fifth line, we defined an account for the lending bank. As it's a liability, it falls under the Liabilities category.

Purchase​

With the accounts set up as above, the act of buying a house is equivalent to

borrowing money (debt) + spending money (down payment) = 1 house in asset

The most important reference when buying a property is likely the Buyer’s Settlement Statement, which clearly outlines the flow of money.

2020-01-01 * "Buying the house"
    Assets:Property:US:CA:123ABC                  1 HOUSE.ABC {1,000,000 USD}
    Assets:Bank:US:SomeBankA                      -100,000 USD
    Assets:Bank:US:SomeBankB                      -101,000 USD
    Liabilities:Bank:US:SomeBank:Mortgage:Loan    -800,000.00 USD
    Expenses:Home:Insurance                       1,000 USD
    Expenses:Home:Mortgage:Loan:ClosingCost

Here, we're detailing the transaction of buying the house, where money flows out from some banks (used for down payment and other expenses), a loan is taken (adding to liabilities), and a house is gained (added to assets).

Pay back mortgages​

Based on the above purchase record, we currently owe 800,000 USD. Due to the interest, and considering that all loans in the US are amortized equally in terms of principal and interest, the monthly payment includes a portion for interest and a portion for principal. In the early stages, the interest constitutes the majority.

To record the loan repayment, all you need to do is check your loan bank's statement. You just need to know how much of the principal you are repaying each month, and the rest is interest. The interest is counted as an Expense.

2020-02-01 * "Mortgage payment"
    Assets:Bank:US:SomeBank:Saving:Joint              -3,372.83 USD
    Liabilities:Bank:US:SomeBank:Mortgage:Loan         1,376.26 USD
    Expenses:Home:Mortgage:Loan:Interest

This entry details the monthly mortgage payment which is subtracted from your joint savings account. The repayment of principal reduces the liability, while the interest part is treated as an expense.

Appreciation​

If you want to record the appreciation of the property, some people create a separate account[, only recording the appreciation of the current property. Considering that the value of the house may increase or decrease, this appreciation may be negative. The advantage of this is that in the summary of your total assets, these two accounts will be included, one for the value of the house at the time of the transaction, and the other for the current appreciation of the house, thus reflecting the real-time price of the house.

I did not adopt this method, mainly for the following reasons:

1. The current value of the house can only be an estimate, for reference only, without practical value. Usually, I can only get the evaluation of the property on websites like Redfin or Zillow, and I personally don't think it has high reference value. I also did not consider incorporating these appreciations into total assets in real time.
2. Personally, I think before the mortgage is paid off, if the cash flow of the house is negative, to some extent, the property is still a liability. Therefore, incorporating it into assets prematurely will give you an illusion of enriched assets and appreciation, and I personally want to avoid this illusion.

The method I use to record property appreciation, which will also be discussed later on how to model RSUs. This method is to use a virtual currency unit. Assuming your base currency is USD, we can use USD.UNVEST (it seems that there is no need to create a new Commodity for this) to indicate that this asset is calculated in a special currency. The growth or reduction of this asset will not be recorded in USD. This way, I can achieve my original goal, that is, to record the appreciation of the house, and this appreciation will not be included in the final balance sheet (Balance Sheet).

2020-01-01 price HOUSE.ABC                          1,000,000 USD
2025-01-01 price HOUSE.ABC                          1,400,000 USD.UNVEST

You only need to price your property to USD.UNVEST regularly.

So, on Fava's Commodity page, you can track the trend of the reference price of the house. But on the Balance Sheet page, the price of the house is still the price of the house at the time of the transaction. That is to say, your total assets are still your down payment money at that time, plus the principal you keep paying off. The final change of this asset should only occur when you buy a house.

Sell​

Because no property has been sold yet and the various miscellaneous fees in the middle are unclear, this is a hypothetical scenario.

Suppose, on January 1, 2025, the property has appreciated to $1,400,000, and some reference data are as follows:

Person A decides to sell the property, and the final selling price of the house is $1,300,000.

2025-01-01 * "Selling the house"
    Assets:Property:US:CA:123ABC                  -1 HOUSE.ABC {1,300,000 USD}
    Liabilities:Bank:US:SomeBank:Mortgage:Loan    709,656.20 USD
    Expenses:Home:Agent:Fee                       72,000 USD
    Expenses:Home:ClosingCost                     10,000 USD
    Expenses:Home:Tax                             90,000 USD
    Assets:Bank:US:SomeBankA

Here it is assumed that 2 out of 5 years are self-occupied, so the appreciation of 500,000 does not need to be taxed. I randomly calculated a number here. In the end, the money that enters Person A's account is $418,343.8, of which 200,000 is the down payment at that time, and about 100,000 in interest has been paid. So, in the end, the book profit for Person A is around 100,000. It is worth noting that my calculation is not fair, after all, Person A has saved rent for these 5 years, and there may be other expenses on the house, such as maintenance, decoration, and so on.

To reflect this in the balance sheet, you can add this pricing.

2025-01-01 price HOUSE.ABC                          1,300,000 USD

Hello everyone! In today's blog post, we're diving into the world of Beancount, a double-entry accounting tool that's loved by many for its simplicity and power. More specifically, we're going to talk about two key concepts: Receivables and Payables.

Understanding these terms is crucial to using Beancount (or any double-entry accounting system) effectively. But don't worry if you're a beginner - we're going to break it all down, step by step!

Receivables and Payables: The Basics​

In accounting, "receivables" and "payables" are terms used to track money that is owed. "Receivables" refers to money that others owe to you, while "payables" refers to money that you owe to others.

Let's take an example:

1. Accounts Receivable (A/R): Suppose you own a bookstore and a customer buys a book on credit. The money they owe you for the book is an account receivable.

2. Accounts Payable (A/P): On the flip side, imagine you order a new set of books from a publisher, but you don't pay for them upfront. The money you owe the publisher is an account payable.

In Beancount, these are typically tracked through corresponding accounts. The main benefit here is that it provides you with a clear and accurate picture of your financial position at any point in time.

Setting Up Receivables and Payables in Beancount​

The structure of your Beancount file can be as simple or as complex as you need it to be. For receivables and payables, you'll likely want to create separate accounts under your Assets and Liabilities sections.

Here is a simple example:

1970-01-01 open Assets:AccountsReceivable
1970-01-01 open Liabilities:AccountsPayable

Tracking Transactions​

Payee side​

After setting up your accounts, you can track transactions that involve receivables and payables. Let's look at an example:

2023-05-29 * "Sold books to customer on credit"
  Assets:AccountsReceivable  100 USD
  Income:BookSales          -100 USD

Here, you're adding $100 to your receivables because a customer owes you this amount. Simultaneously, you're reducing your income by the same amount to maintain the balance (since you haven't actually received the money yet).

When the customer eventually pays, you'll record it like this:

2023-06-01 * "Received payment from customer"
  Assets:Bank:Savings        100 USD
  Assets:AccountsReceivable -100 USD

Payer side​

The same principle applies for payables, but with reversed signs:

2023-05-30 * "Bought books from publisher on credit"
  Liabilities:AccountsPayable  200 USD
  Expenses:BookPurchases     -200 USD

And when you pay off your debt:

2023-06-02 * "Paid off debt to publisher"
  Liabilities:AccountsPayable -200 USD
  Assets:Bank:Checking        200 USD

Wrapping Up​

Receivables and payables are at the heart of any accounting system. By accurately tracking these, you gain a comprehensive understanding of your financial health.

This is just a starting point, and Beancount is capable of much more. I hope this blog post helps clarify these important concepts. As always, happy accounting!

In today's blog post, we will be breaking down a Beancount ledger for businesses, which will help you understand the intricacies of this plain text double-entry accounting system.

Let's start with the code first:

1970-01-01 open Assets:Bank:Mercury
1970-01-01 open Assets:Crypto

1970-01-01 open Equity:Bank:Chase

1970-01-01 open Income:Stripe
1970-01-01 open Income:Crypto:ETH

1970-01-01 open Expenses:COGS
1970-01-01 open Expenses:COGS:Contabo
1970-01-01 open Expenses:COGS:AmazonWebServices

1970-01-01 open Expenses:BusinessExpenses
1970-01-01 open Expenses:BusinessExpenses:ChatGPT

2023-05-14 * "CONTABO.COM" "Mercury Checking ••1234"
  Expenses:COGS:Contabo                               17.49 USD
  Assets:Bank:Mercury                                -17.49 USD

2023-05-11 * "Amazon Web Services" "Mercury Checking ••1234"
  Expenses:COGS:AmazonWebServices                  14490.33 USD
  Assets:Bank:Mercury                             -14490.33 USD

2023-03-01 * "STRIPE" "Mercury Checking ••1234"
  Income:Stripe                                   -21230.75 USD
  Assets:Bank:Mercury                              21230.75 USD

2023-05-18 * "customer_182734" "0x5190E84918FD67706A9DFDb337d5744dF4EE5f3f"
  Assets:Crypto                                         -19 ETH {1,856.20 USD}
  Income:Crypto:ETH                                      19 ETH @@ 35267.8 USD

Understanding the Code​

1. Opening Accounts: The code starts by opening a series of accounts on 1970-01-01. These include a mix of asset accounts (Assets:Bank:Mercury and Assets:Crypto), an equity account (Equity:Bank:Chase), income accounts (Income:Stripe and Income:Crypto:ETH), and expense accounts (Expenses:COGS, Expenses:COGS:AmazonWebServices, Expenses:BusinessExpenses, and Expenses:BusinessExpenses:ChatGPT).

2. Transactions: It then progresses to record a series of transactions between 2023-03-01 and 2023-05-18.

   • The transaction on 2023-05-14 represents a payment of $17.49 to CONTABO.COM from Mercury Checking ••1234. This is recorded as an expense (Expenses:COGS:Contabo) and a corresponding deduction from the Assets:Bank:Mercury account.

   • Similarly, the transaction on 2023-05-11 represents a payment of $14490.33 to Amazon Web Services from the same bank account. This is logged under Expenses:COGS:AmazonWebServices.

   • The transaction on 2023-03-01 shows income from STRIPE being deposited into Mercury Checking ••1234, totaling $21230.75. This is recorded as income (Income:Stripe) and an addition to the bank account (Assets:Bank:Mercury).

   • The last transaction on 2023-05-18 represents a crypto transaction involving 19 ETH from a customer. This is tracked under Assets:Crypto and Income:Crypto:ETH. The {1,856.20 USD} shows the price of ETH at the time of transaction, while the @@ 35267.8 USD specifies the total value of the 19 ETH transaction.

In all transactions, the principle of double-entry accounting is maintained, ensuring that the equation Assets = Liabilities + Equity always holds true.

Final Thoughts​

This Beancount ledger provides a straightforward yet robust system for tracking financial transactions. As seen in the final transaction, Beancount is flexible enough to account for non-traditional assets like cryptocurrency, which is a testament to its utility in our increasingly digital financial landscape.

We hope this breakdown helps you better understand the structure and capabilities of Beancount, whether you're a seasoned accountant or a beginner trying to keep track of your personal finances. Stay tuned for our next blog post, where we'll delve further into advanced Beancount operations.

We are thrilled to announce that as of May 1st, 2023, we will be reintroducing the free plan for new customers. This decision comes after making significant improvements to our platform and optimizing our resources in order to better serve all of our customers, both free and paid.

The free plan has always been an essential part of our vision to provide an accessible and user-friendly service for everyone. We believe that the changes we've made over the past months will allow us to deliver an even better experience for our users while maintaining the quality of service for our Pro plan customers.

New customers who register after May 1st, 2023, will have access to the Free plan.

Your support and loyalty have been instrumental in making this reintroduction of the free plan financially possible. It is through your contributions that we have been able to invest in our infrastructure and support systems, ensuring that we can continue to deliver the high-quality service you expect while also expanding access to our platform for new users. Your commitment to our vision has helped us grow and evolve, and we are truly grateful for your ongoing partnership. Together, we are building a thriving community and empowering users from all walks of life to achieve their goals.

If you have any questions or concerns, please don't hesitate to reach out to us. We are always here to listen to your feedback and address any issues you may have. Thank you for your continued support, and we look forward to providing you with the best service possible.

Example Account Name​

Assets:US:BofA:Checking

Account Types​

Assets          +
Liabilities     -
Income          -
Expenses        +
Equity          -

Commodities​

CNY, EUR, CAD, AUD
GOOG, AAPL, RBF1005
HOME_MAYST, AIRMILES
HOURS

Directives​

General syntax

YYYY-MM-DD <Directive> <Parameters...>

Opening & Closing Accounts​

2001-05-29 open Expenses:Restaurant
2001-05-29 open Assets:Checking     USD,EUR  ; Currency constraints

2015-04-23 close Assets:Checking

Declaring Commodities (Optional)​

1998-07-22 commodity AAPL
  name: "Apple Computer Inc."

Prices​

2015-04-30 price AAPL   125.15 CNY
2015-05-30 price AAPL   130.28 CNY

Notes​

2013-03-20 note Assets:Checking "Called to ask about rebate"

Documents​

2013-03-20 document Assets:Checking "path/to/statement.pdf"

Transactions​

2015-05-30 * "Some narration about this transaction"
  Liabilities:CreditCard   -101.23 CNY
  Expenses:Restaurant       101.23 CNY

2015-05-30 ! "Cable Co" "Phone Bill" #tag ˆlink
  id: "TW378743437"               ; Meta-data
  Expenses:Home:Phone  87.45 CNY
  Assets:Checking                 ; You may leave one amount out

Postings​

  ...    123.45 USD                             Simple
  ...        10 GOOG {502.12 USD}               With per-unit cost
  ...        10 GOOG {{5021.20 USD}}            With total cost
  ...        10 GOOG {502.12 # 9.95 USD}        With both costs
  ...   1000.00 USD   @ 1.10 CAD                With per-unit price
  ...        10 GOOG {502.12 USD} @ 1.10 CAD    With cost & price
  ...        10 GOOG {502.12 USD, 2014-05-12}   With date
  ! ...   123.45 USD ...                        With flag

Balance Assertions and Padding​

; Asserts the amount for only the given currency:
2015-06-01 balance Liabilities:CreditCard  -634.30 CNY

; Automatic insertion of transaction to fulfill the following assertion:
2015-06-01pad Assets:Checking Equity:Opening-Balances

Events​

2015-06-01 event "location" "New York, USA"
2015-06-30 event "address" "123 May Street"

Options​

option "title" "My Personal Ledger"

Other​

pushtag #trip-to-peru
...
poptag  #trip-to-peru
; Comments begin with a semi-colon

Discover the Magic of Plain Text Accounting with Beancount

Introduction​

Welcome to a world where accounting is no longer a daunting task. Today, we introduce you to Beancount, a powerful, flexible, and intuitive plain text accounting tool. Beancount empowers you to take control of your finances by providing a transparent and straightforward approach to managing your money.

In this comprehensive guide, we will delve into the basics of Beancount, explain its core concepts, and walk you through its simple yet powerful features. By the end of this blog, you'll have a solid understanding of Beancount and be ready to start using it to organize and analyze your financial life.

What is Beancount?​

Beancount is an open-source, plain text accounting system created by Martin Blais. Inspired by John Wiegley's Ledger system, Beancount aims to provide a robust and reliable method to manage personal and small business finances using plain text files. With Beancount, you can track your income, expenses, investments, and much more with ease.

Why Beancount?​

Plain text accounting offers several advantages over traditional spreadsheet-based or software-based accounting systems:

• Transparency: Beancount files are human-readable, making it easy to understand and audit your financial data.
• Flexibility: Beancount can be easily customized to fit your specific needs, and you can use your favorite text editor and version control system to manage your financial data.
• Portability: Your financial data can be accessed on any device, and it's easy to transfer between systems or share with others.
• Future-proof: Plain text files are universally compatible, ensuring that your financial data will remain accessible, even as technology evolves.

Beancount's Core Concepts​

To use Beancount effectively, it's crucial to understand its core concepts:

• Transactions: Financial events, such as income, expenses, or transfers between accounts, are recorded as transactions.
• Accounts: Transactions involve one or more accounts, such as assets, liabilities, income, or expenses.
• Double-entry bookkeeping: Beancount enforces double-entry bookkeeping, ensuring that every transaction has balanced debits and credits.
• Directives: Beancount uses a set of directives to define transactions, account openings, and other financial events.

Getting Started with Beancount​

To start using Beancount, follow these simple steps:

• Install Beancount: Install Beancount on your system using the provided installation instructions for your operating system.
• Create your Beancount file: Create a new plain text file with the .beancount extension (e.g., my_finances.beancount).
• Define your accounts: Use the "open" directive to define the accounts you'll use in your transactions.
• Record transactions: Use the "txn" directive to record your financial transactions.

Or simply sign up at https://beancount.io. Here are some plain text accounting examples -

Example 1: Basic Transaction

2023-04-01 open Assets:Checking
2023-04-01 open Expenses:Groceries

2023-04-10 txn "Grocery Store" "Buying groceries"
  Assets:Checking         -50.00 USD
  Expenses:Groceries       50.00 USD

In this example, we open two accounts, Assets:Checking and Expenses:Groceries. On April 10, 2023, we record a transaction for buying groceries worth $50. The transaction reduces the balance of Assets:Checking by $50 (debit) and increases the balance of Expenses:Groceries by $50 (credit).

Example 2: Income and Expense Transaction

2023-04-01 open Assets:Checking
2023-04-01 open Income:Salary
2023-04-01 open Expenses:Rent

2023-04-05 txn "Employer" "Salary payment"
  Assets:Checking       2000.00 USD
  Income:Salary        -2000.00 USD

2023-04-06 txn "Landlord" "Monthly rent payment"
  Assets:Checking       -1000.00 USD
  Expenses:Rent          1000.00 USD

In this example, we open three accounts: Assets:Checking, Income:Salary, and Expenses:Rent. On April 5, 2023, we record a salary payment transaction of $2000. The transaction increases the balance of Assets:Checking by $2000 (credit) and decreases the balance of Income:Salary by $2000 (debit). On April 6, 2023, we record a rent payment transaction of $1000. The transaction reduces the balance of Assets:Checking by $1000 (debit) and increases the balance of Expenses:Rent by $1000 (credit).

Example 3: Transfer Between Accounts

2023-04-01 open Assets:Checking
2023-04-01 open Assets:Savings

2023-04-15 txn "Bank" "Transfer from Checking to Savings"
  Assets:Checking       -500.00 USD
  Assets:Savings         500.00 USD

In this example, we open two accounts: Assets:Checking and Assets:Savings. On April 15, 2023, we record a transaction to transfer $500 from the checking account to the savings account. The transaction reduces the balance of Assets:Checking by $500 (debit) and increases the balance of Assets:Savings by $500 (credit).

These examples illustrate the basic concepts of Beancount's double-entry bookkeeping system. By properly recording transactions, users can maintain accurate records of their financial activities and generate reports to gain insights into their financial situation.

Generating Reports and Analyzing Data​

Beancount comes with a set of powerful tools for generating financial reports, including balance sheets, income statements, and more. You can also use Fava, a web-based user interface for Beancount, to visualize and interact with your financial data. https://beancount.io is built upon Fava with MIT license.

Conclusion​

Embrace the power and simplicity of plain text accounting with Beancount. By understanding its core concepts and following the steps outlined in this guide, you'll be well on your way to managing your personal or small business finances with ease and precision. As you grow more comfortable with Beancount, you can explore advanced features and customizations to tailor the system to your unique needs.

Whether you're looking to track your spending, plan for the future, or gain insights into your financial habits, Beancount offers the flexibility and transparency needed to achieve your goals. With its user-friendly approach, Beancount has the potential to revolutionize the way you manage your finances and empower you to take control of your financial future.

Now that you have a solid foundation in Beancount, it's time to embark on your plain text accounting journey. Say goodbye to cumbersome spreadsheets and convoluted software, and welcome the world of Beancount. Happy accounting!

Beancount, the double-entry accounting system beloved by developers and finance nerds alike, is powerful in its simplicity. But for those who want more control and faster navigation inside Fava, Beancount’s web interface, custom sidebar links and SQL queries can take your workflow to the next level.

In this guide, we’ll show you how to:

• Add quick-access links to Fava’s sidebar
• Use SQL queries for advanced filtering and analysis
• Customize your workflow for monthly reviews or anomaly detection

Why Customize Fava?​

Fava is already a beautiful interface for viewing your Beancount ledger, but as your journal grows, so does the need for better shortcuts and smarter queries.

Pain points this solves:​

• Navigating through time ranges repeatedly
• Filtering transactions across nested accounts
• Spotting negative balances or anomalies faster

✨ Custom Sidebar Links​

Let’s start with improving your daily workflow with simple sidebar shortcuts. These links appear in Fava’s left sidebar and can take you directly to filtered views like this month’s transactions or last month’s income.

Add these lines to your Beancount file:

2021-01-01 custom "fava-sidebar-link" "Current Month" "/jump?time=month"
2021-01-01 custom "fava-sidebar-link" "Last Month" "/jump?time=month-1"
2021-01-01 custom "fava-sidebar-link" "Clear All" "/jump?account=&time=&filter="

What They Do:​

• Current Month: Opens the transaction view filtered to the current month.
• Last Month: Instantly jumps to the previous month—great for end-of-month reviews.
• Clear All: Resets filters, showing all entries again.

These shortcuts eliminate manual time input and make your Fava experience feel more fluid and personalized.

🔍 Custom SQL Queries​

For deeper insight, Fava’s SQL interface is incredibly powerful. Here’s a query that finds all negative balances in accounts that match a pattern—perfect for flagging unusual or problematic transactions.

SELECT account, units(sum(position)), sum(position)
WHERE number(units(position)) < 0
  AND account ~ '.*:BCM:.*'
  AND date >= DATE(2021,12,9)
  AND date < DATE(2022,1,9)

Breakdown:​

• account ~ '.*:BCM:.*': Filters accounts containing :BCM: in their name.
• number(units(position)) < 0: Flags negative balances (e.g. overspent budgets).
• Date filters narrow the result to a specific 1-month window.

Use cases:​

• Spot errors like duplicate expenses or incorrect postings
• Audit a specific vendor or category
• Quickly extract actionable insights for budgeting

🛠 Pro Tip: Combine Links + Queries​

While Fava doesn’t allow direct links to custom queries, you can create a monthly review habit by:

• Using the “Current Month” link to start your review
• Opening your saved queries tab in another pane
• Reviewing both simultaneously—filter first, then dig deep

This combo helps you catch anomalies before they spiral and ensure your ledger stays clean.

Final Thoughts​

Beancount is minimal by design, but small enhancements like these bring huge gains in efficiency. Whether you’re reviewing your budget, debugging strange balances, or simply saving clicks, custom links and SQL queries give you more power and less friction.

Bonus: If you're using Fava’s custom reports, you can even build full dashboards tailored to your personal finance rituals.

Ready to take control?

Start small: add the “Current Month” link. Then build your own queries. Your future self will thank you.

Want more tips like this? Subscribe to our newsletter or explore more Beancount recipes at Beancount.io.