Community Showcase

Real-World Beancount Setups

Introduction

Beancount is a versatile plain-text accounting system, and its users have molded it to fit a wide range of real-world needs. In this community showcase, we present anonymized examples of how different people structure and use their Beancount accounting workflows – from freelancers and small business owners to personal finance enthusiasts. These examples highlight creative practices like tagging transactions with metadata, automating ledger updates with custom scripts, handling multiple currencies, budgeting and forecasting, and extending Beancount with plugins or integrations (such as the Fava web interface). The goal is to inspire and inform accountants, developers, and finance-savvy users about what’s possible with Beancount’s flexible system.

Example Fava interface: Many Beancount users rely on Fava – an open-source web dashboard – to visualize their finances. Fava can turn a Beancount ledger into interactive reports and charts. For example, the screenshot above shows an Income Statement treemap breaking down income and expenses by category, giving a quick overview of where money is coming from and going. Users can filter this view by time, account, or tags to drill into specific projects or periods. Such visualizations help make plain-text data more accessible, allowing users to spot trends and anomalies at a glance.

Each Beancount setup is unique, but common themes emerge. Below, we dive into three scenarios – a freelancer, a small business owner, and a personal finance power-user – to see how they organize their accounts and leverage Beancount’s features. All personal details have been removed or generalized, focusing only on techniques and configurations.

Freelancer: Project Tagging and Invoice Tracking

Our first example is a freelance consultant who uses Beancount as the backbone of their business finances. This freelancer’s ledger is organized to track income and expenses per project and to manage invoices for multiple clients. They’ve set up dedicated accounts for Accounts Receivable (A/R) under Assets for each client, which helps segregate who owes what. When they complete a project and invoice a client, they record a transaction debiting the client’s A/R account and crediting an income account. For instance, a new invoice might be recorded as:

2025-08-01 * "Project X Completed" ^INV-0001
    Assets:AccountsReceivable:ClientA   5,000 USD
    Income:Consulting                   -5,000 USD

Here the ^INV-0001 notation is a link (a built-in Beancount metadata feature) used to tag this transaction with the invoice number. When the client pays part or all of that invoice, the payment transaction includes the same ^INV-0001 link, which ties the two entries together. This linking makes it easy to allocate payments to specific invoices and see outstanding balances. As one community member explained, you can use such tags or links to mark partial payments – e.g. a $20 payment against a $30 invoice – on both the invoice entry and the payment entry. By querying the ledger for that invoice link, the freelancer can instantly see how much of the invoice has been paid and what remains open.

In addition to links, the freelancer heavily uses tags for categorization. Tags in Beancount are labels prefixed with # that can mark transactions for later filtering. This user tags each expense that is billable to a client with the project’s code, like #ProjectX, and tags reimbursable expenses with #Reimbursable. For example, if they buy airline tickets for a client project, the expense entry might include #ProjectX #Reimbursable. This practice allows generating reports per project or client by filtering on tags. After a project, the freelancer can run a query to list all #Reimbursable expenses for that project and ensure they invoice the client for each. One Beancount user noted that tagging work-trip expenses helped catch any that weren’t reimbursed – ideally, a work trip’s expenses net out to $0 when all refunds from the client are received. This highlights how tagging, combined with Beancount’s query capabilities, provides an extra layer of oversight for freelancers managing billable expenses.

To manage the status of outstanding payments, our freelancer uses a special convention for pending receivables. They apply the tag #UNRESOLVED to any invoice transaction that hasn’t been fully paid yet. Beancount (and Fava) doesn’t enforce this tag, but it’s a community-established pattern to mark transactions awaiting settlement. For example, until Client A pays the full $5,000, the invoice transaction above would include #UNRESOLVED. By filtering on that tag, the freelancer can list all open invoices at any time. Once payment is received and applied (the corresponding A/R transaction is entered), they remove or ignore the #UNRESOLVED tag, and the receivable account for that client will balance to zero. This system ensures no invoice “falls through the cracks.” It’s essentially an aging report done in plain text – if an A/R remains non-zero and tagged unresolved, it needs attention.

Because freelancers often deal with multiple payment methods and sometimes multiple currencies, the Beancount setup accommodates that seamlessly. In our example, the consultant might bill some clients in USD and others in EUR. Multi-currency handling is straightforward in Beancount: any account can hold multiple commodities (currencies are treated as commodities). The freelancer can either keep separate subaccounts for each currency (e.g. Assets:AccountsReceivable:ClientA:EUR vs ...:USD), or simply post transactions in the appropriate currency under the same account. Beancount will track balances per currency automatically. One user emphasized how nice it is that “Beancount can track quantities in any currency, whether USD or a ticker symbol,” all in one ledger. Our freelancer takes advantage of this by recording exchange rates with price directives whenever they need to convert currencies for reporting. They can generate an income report converted to their home currency once they’ve entered periodic exchange rates or market prices.

Finally, this freelancer integrates their Beancount ledger with practical tools to streamline their workflow. For instance, they attach PDF copies of each invoice to the ledger using document metadata. A typical invoice payment entry might look like:

2025-08-30 * "ClientA" "Payment for INV-0001" ^INV-0001
    Assets:Bank:Checking       5,000 USD
    Assets:AccountsReceivable:ClientA  -5,000 USD
    document: "Invoices/ClientA/INV-0001.pdf"

Beancount’s document directive or metadata allows associating files with entries, and Fava will show a hyperlink for these attachments. This means the freelancer (or their accountant) can click directly from the ledger report to view the original invoice PDF, ensuring easy access to backup documentation. The freelancer also uses Fava’s reports to monitor her business: by filtering the Income Statement or Balance Sheet by client, she can see profitability per client and check that all projects are paid up. In summary, this freelancer’s Beancount system demonstrates heavy use of tagging and linking to manage project-based accounting. It turns a plain text ledger into a robust freelance accounting tool, with clear visibility into project expenses, multi-currency income, and invoice statuses.

Key practices in the Freelancer setup: Using tags to group transactions by project or purpose, linking invoices and payments with unique IDs, marking outstanding receivables with an #UNRESOLVED tag, attaching invoice documents to ledger entries for reference, and leveraging Beancount’s multi-currency support to bill international clients without hassle. All of these are achieved with plain text entries plus a few helper tools, showcasing the power of metadata in Beancount.

Small Business: Automation and Multi-Currency Accounting

Next, we look at a small business owner – specifically a startup founder – who adopted Beancount to run the company books. Small businesses have needs similar to freelancers (invoices, expenses, multi-currency) but often on a larger scale and with a greater emphasis on automation, consistency, and collaboration. In this case, the founder was technically savvy and built a highly automated Beancount workflow to minimize manual bookkeeping. After evaluating traditional accounting software like QuickBooks, they opted for Beancount’s plain-text approach to retain full control of the data. Over a few years, they iteratively developed custom tools to achieve a 95% automated bookkeeping process.

Automated imports and reconciliation: One of the first challenges was importing transactions from various sources (bank accounts, credit cards, payment processors) into the ledger. Instead of typing in each transaction, this user set up import scripts to fetch and translate data into Beancount format. They wrote custom Python importers for each financial institution’s CSV or API format, so that with one command they can pull new transactions and append them to the ledger. For example, using Beancount’s bean-extract framework, the founder can run a script that scans a downloads folder for new statements and outputs them as Beancount entries. Another user, Rhyd Lewis, described a similar setup where he has separate importer scripts for each bank and can invoke them via a simple command (using a Justfile) to update his ledger. Our small business owner does the same – all bank transactions, credit card swipes, and even PayPal or Stripe transactions are automatically fetched and added to the books, categorized with appropriate accounts.

To ensure data integrity even as these entries are added automatically, they also use Beancount’s validation tools and plugins. For instance, the beancount.plugins.noduplicates plugin is enabled to prevent accidentally importing the same transaction twice, and beancount.plugins.nounused flags any accounts that have no entries (helpful for cleaning up stale accounts). The founder also uses a formatter (like bean-format or the community tool beancount-black) to keep the ledger file consistently styled. This matters because with many automated edits, having a uniform style makes diffs and audits easier. In fact, the founder keeps the ledger in a Git repository, treating ledger updates like code changes. Every new batch of imported transactions becomes a Git commit, and they can review diffs to see what changed. In one screenshot, they show a Git history where a credit card transaction for “Costco” goes from a pending state to cleared in the ledger, all without manual intervention. Version control provides an audit trail: they can see exactly when a transaction was added or modified and even revert changes if something was imported incorrectly. This is a great example of bringing software development best practices (like source control) into accounting records.

Multi-currency and international transactions: Small businesses often transact in multiple currencies – for example, a startup might have USD expenses but also receive payments in EUR or hold a GBP bank account. Our showcase company uses Beancount’s multi-currency features to consolidate all this in one ledger. They opened separate accounts for each currency (e.g. Assets:Bank:Checking:USD and Assets:Bank:Checking:EUR), which is one common approach. However, even if different currencies share an account, Beancount will track each currency’s balance separately and require that transactions balance per currency. The founder frequently runs valuation reports to see the company’s total balances converted to the base currency. Since Beancount supports price lookups, he set up daily price feeds for currency exchange rates (and stock prices for any investments) using the bean-price tool or a plugin. The result is that at any time he can generate a balance sheet in, say, USD that includes the EUR account translated at the latest rate. Community members point out that handling multiple currencies in ledger-style accounting is simple – you just add transactions in the given currency and record exchange rates as needed. For instance, one user shared an example of converting USD to EUR to CAD through intermediate accounts as a way to manage currency conversions in Beancount. In our case, the small business doesn’t necessarily convert currencies in transactions (they keep them in native currency) but uses reports to consolidate. This flexibility has been crucial as the startup expanded globally.

Custom scripts and extensions: Not everything the founder needed was available out-of-the-box, so they extended Beancount with custom plugins. Over time, they ended up writing a parser library, a formatting tool, and a rule-based transaction importer, releasing many of these as open-source packages. For example, they built a rule-based import engine that uses a YAML configuration to categorize transactions automatically. A snippet of this configuration shows how specific payees or descriptions (like “Comcast” or “PG&E”) are mapped to certain expense accounts and narrations, so that when those appear in a bank feed, the correct Beancount entry is generated without manual editing. This is essentially a custom automation to apply bookkeeping rules (for utilities, subscriptions, etc.) on the fly. Another plugin ensures the ledger always stays balanced and formatted. All these tools run as part of the founder’s workflow whenever new data is ingested. The result is a ledger that “updates itself” with minimal intervention, which the founder says brings him “pure joy” as an automation-obsessed developer.

Security and accessibility were also concerns. The founder wanted his finance team (and even his spouse, acting as an overseer) to be able to view the books easily. For this, he set up a private deployment of Fava in the cloud. Every time he pushes a new ledger commit to the private Git repository, a CI pipeline (using GitHub Actions and AWS Elastic Beanstalk) deploys an updated Fava instance. The web interface is behind a password (using an Nginx proxy with basic auth), so only authorized people can see it. This way, the latest financial statements are always available through a browser dashboard, without needing to install anything locally. The architecture diagram below illustrates this setup: the Beancount file and necessary config are bundled into a Docker image along with Fava, and served on AWS, with Cloudflare in front for security.

Automating Beancount in the cloud: This diagram shows a deployment pipeline for a Beancount ledger + Fava. The user updates the ledger file locally and pushes to Git; a Docker container (including Fava and Nginx for auth) is built and deployed to an AWS Beanstalk server, and Cloudflare acts as a proxy. The result is a secure web portal where the small business’s finance data can be accessed from anywhere (by the owner or team) in real-time. This advanced setup demonstrates how a small business can integrate Beancount with modern cloud tools to achieve convenience without giving up data ownership.

In day-to-day use, the small business owner’s focus is on exception handling rather than data entry. Each month, he briefly reviews the automatically imported transactions (using Git diffs or Fava’s journal view) to catch any uncategorized or incorrect entries. He also uses Beancount’s balance assertions to reconcile accounts. For example, after entering all June transactions, he might add a balance check to confirm that the bank account’s ending balance matches the statement; if not, Beancount will error out, indicating something is missing or mis-entered. This ensures the books remain accurate.

Key practices in the Small Business setup: Heavy automation through custom importers and scripts (making the ledger “95% automatic”), use of version control for audit trails and collaboration, multi-currency accounting with price feeds for valuation, and deployment of Fava for easy, shareable access to financial reports. The small business scenario shows how far Beancount can be taken with engineering effort – turning accounting into a largely automated pipeline while preserving transparency and flexibility. Even if one isn’t a programmer, many of these benefits can be achieved by using community plugins (for formatting, duplicate detection, etc.) and by adopting the plain-text workflow that encourages frequent reviews and backups.

Personal Finance Enthusiast: Budgeting and Custom Analysis

Our final showcase is a personal finance enthusiast – someone using Beancount to manage household finances and investments with a high level of detail. This user treats their personal finances with the rigor of an accountant and the curiosity of a data analyst. The result is a Beancount ledger that not only tracks every penny, but also serves as a base for budgeting, forecasting, and analytical experiments.

Organizing the personal ledger: Many individuals start with a single Beancount file for all their accounts, and this enthusiast is no different. They maintain one master ledger (e.g. main.beancount) that includes all accounts (bank accounts, credit cards, loans, investment portfolios, etc.) and transactions. Over time, they introduced some structure by splitting out sections – for example, they have a file for opening/closing accounts and separate files for annual transactions – which are included into the main file. This modular organization makes it easier to navigate years of data (one can archive old years in separate files) while still being logically one ledger. Another personal user on the community forum described a similar layout: a main file that includes others by category (e.g. Income.beancount, Expenses.beancount, Investments.beancount). Our enthusiast keeps it straightforward for now: one file synced across devices.

Speaking of syncing, because it’s personal finance, this user wants to capture transactions wherever they are. They use a mobile app called Beancount Mobile to quickly add entries on the go (for example, logging a cash expense right at the store). The ledger file is shared via a cloud-sync (Syncthing, in this case) so that their phone, laptop, and a VPS (server) all have the latest copy. On a computer, they prefer using Emacs with beancount-mode for comfortable editing with syntax highlighting. This setup ensures that whether they’re at their desk or out and about, they can record transactions immediately and avoid forgetting anything. It’s a great example of adapting tech tools for personal convenience – effectively building a self-hosted alternative to commercial budgeting apps.

Tagging and metadata for granular tracking: This user takes advantage of tags to add a second dimension to their data beyond the chart of accounts. For regular budgeting categories, accounts suffice (they have accounts like Expenses:Groceries, Expenses:Rent, etc.), but for cross-cutting themes like events or goals, they use tags. For example, they tag all transactions related to their home renovation project with #HomeReno, whether it’s buying lumber at a hardware store (expense) or receiving a rebate from a manufacturer (income). This way, they can generate a report of total project cost easily without those expenses being siloed under different accounts. One Reddit user demonstrated this approach by tagging expenses like #garage-improvement or #lighting-improvement for home projects, making it trivial to filter and sum those via Beancount’s queries. Our enthusiast does the same for vacations (#ItalyTrip2025), major purchases, and one-off events.

Metadata (key-value pairs on transactions) is also used for some specific purposes. For instance, they add a location: ... metadata to big expenses to track where they spent the money, or a note: ... for additional context beyond the payee and narration. In a few cases, they even created custom metadata fields to help with forecasting. One example is adding budget: X and frequency: monthly to certain recurring expenses – an idea inspired by a discussion on the Beancount mailing list where a user was storing budget projections in metadata for each expense. Those metadata fields don’t affect Beancount’s core, but the enthusiast wrote a small Python script that reads them and compares the actual spending to the projected budget. This is an alternative to using Fava’s built-in budgets (described below), showing how metadata can be bent to the user’s will. As the Beancount creator noted, metadata is “only there for you [to use in custom scripts] – Beancount parses it but ignores it” by itself. In short, this user isn’t afraid to extend the ledger with extra info to assist their personal analysis.

Budgeting with Beancount: One of the main goals for this user is to stick to a monthly budget. They previously used a budgeting app (YNAB) and wanted to replicate some of its envelope budgeting concepts. There are a few ways to do budgeting in Beancount, but the easiest is using Fava’s budget directives. Our enthusiast adds budget entries in the ledger like so:

2025-01-01 custom "budget" Expenses:Groceries   "monthly" 500 USD
2025-01-01 custom "budget" Expenses:DiningOut   "monthly" 200 USD
2025-01-01 custom "budget" Expenses:Travel      "yearly" 3000 USD

Each line sets a budget for an account (category) over a period. Fava then displays budget vs actual bars in the web interface, letting the user see, for example, that they spent 480 USD on Groceries this month out of the 500 budgeted, and maybe 220 on DiningOut (over budget). The enthusiast checks Fava’s Income Statement and Expenses reports regularly, which show both monthly totals and the budget targets. Fava conveniently rolls up the daily/weekly budgets into the appropriate time spans. By using the Fava UI for this, the user doesn’t need a separate spreadsheet for budgeting; it’s all integrated. (They also experimented with a more automated “envelope” system by moving funds into dummy accounts at the start of each month, as suggested on the forums, but found the custom budget directives simpler to maintain.)

For forecasting, beyond budgets, they keep an eye on upcoming bills. Some community members have built plugins to generate future transactions for subscriptions or loan amortization schedules, but this user opted for a simpler approach: they maintain a separate section of the ledger with future-dated transactions for known items (like next month’s rent, or an upcoming annual insurance payment). Those remain in the ledger but don’t affect today’s balances, and once the date arrives and the transaction becomes current, it serves as a reminder (and they’ll adjust the amount if needed to match the actual charge). It’s a bit of a hack, but it works for forecasting cash flow without complex tooling.

Investment tracking and multi-commodity accounting: As a finance enthusiast, this user also uses Beancount to consolidate investment accounts – stocks, mutual funds, and crypto – alongside cash accounts. They have brokerage accounts whose holdings (e.g. shares of AAPL, GOOG, etc.) are recorded in Beancount as commodities. For example, buying 10 shares of Apple would be an entry that credits the brokerage cash and debits an asset account with 10 AAPL as the commodity amount. Beancount’s ability to handle any commodity is very useful here; one can mix currencies and stocks freely. “Beancount can track quantities in any currency, whether USD or a ticker symbol,” as one user pointed out, which was a big improvement over personal finance apps that often don’t support stock positions well. Our enthusiast uses the bean-price tool on a nightly cron job to fetch the latest market prices for all their securities and foreign currencies. Every night at 4am, a script runs bean-price which pulls prices (from Yahoo Finance or another source) and appends price records to the ledger for that day. This way, the next time they open Fava or run a report, they can see up-to-date portfolio values and even investment performance over time. The entire net worth, across bank accounts, retirement funds, and crypto wallets, is available in one unified view. This is a dream for a data-driven investor: no need to log into multiple platforms to see the whole picture. They’ve essentially built a personal financial dashboard powered by Beancount.

Analysis and integration: What truly sets this personal finance power-user apart is how they analyze the data once it’s in Beancount. With all transactions in a SQLite database (Beancount can query data via its built-in query language, which is SQL-like), the user can do custom analysis. They wrote Python scripts to answer questions like “What’s the 3-month moving average of my grocery spending?” or “How does this year’s spending on utilities compare to last year?” One script queries the ledger for specific tags and outputs results to a Pandas dataframe for further number-crunching. Because the ledger is plain text, they have also used Jupyter notebooks to experiment with different visualizations (beyond what Fava offers). For example, they produced a custom bar chart of monthly savings rate using Matplotlib by aggregating Beancount data in Python. This kind of ad-hoc analysis is possible only because Beancount keeps data accessible and machine-readable. As one user put it, extracting data is trivial – “I have one Python script that pulls data out of Beancount using the query language, and then I use a pandas dataframe to prepare the data into a report”. Our enthusiast has a repository of little scripts like this that they run for their annual financial review.

Of course, not everything requires coding – much of the time, they rely on Fava’s built-in charts. Fava provides a net worth line chart, income vs expenses trend, and even a treemap breakdown (as shown earlier) that are all just a click away. The user appreciates that the entire history of their finances since 2018 is queryable and auditable. For instance, if they wonder “how much have I spent on car repairs in the last 5 years,” they can write a quick query or filter in Fava to get the answer, instead of digging through receipts. This empowerment is exactly what attracted them to Beancount: full ownership of data and infinite flexibility in analysis. As a bonus, the plain text ledger is future-proof – it can be version controlled, migrated, or even parsed by other tools if needed. Unlike a closed-source app, there’s no risk of losing access to their financial history.

Key practices in the Personal setup: Utilizing mobile and desktop tools for convenient data entry, using tags and custom metadata to track life events and cross-category groupings, implementing budgets through Fava’s budget directives for ongoing spending targets, tracking investments and multiple currencies in the same ledger (with automated price updates), and performing custom analysis by querying the ledger data directly. This case shows that with a bit of setup, even personal finance enthusiasts can achieve a level of insight and control typically reserved for businesses – all while keeping things fun and engaging for a tech-savvy user.

Conclusion

Across these community examples, a clear theme is that Beancount’s flexibility enables a highly personalized accounting system. Power users in the community have leveraged simple text files to build solutions that rival commercial software in capability, yet are tailor-made to their workflows. Freelancers tag and link entries to manage client projects and invoices with ease. Small business owners script away tedious bookkeeping tasks and integrate Beancount with modern infrastructure for always-updated financials. Personal finance enthusiasts use the ledger as a single source of truth for budgeting, investing, and decision-making, augmenting it with tags and tools to answer virtually any question about their money. All of this is achieved while maintaining the core advantages of plain-text accounting: transparency, auditability, and control over one’s data.

Beancount’s community has also produced a rich ecosystem of plugins and integrations. From editor modes and mobile apps for input, to the Fava web interface for visualization, to countless importers and utilities on GitHub, there are resources to accommodate nearly every need. Users frequently share their ledger setups on forums and blogs, so others can learn and adopt best practices. Importantly, sensitive information can be kept private (or easily redacted for sharing) due to the human-readable format – as we’ve done in this showcase. The examples above demonstrate that whether you are a freelance developer, a startup founder, or a personal finance nerd, you can bend Beancount to your will. By using tagging and metadata creatively, automating where possible, handling multi-currency transactions, planning with budgets, and extending via plugins, the community continues to push the boundaries of what’s possible in plain text. The result is professional-grade accounting ledgers that are also engaging to maintain, giving users both clarity and control over their finances.