Essential Beancount Native Plugins You Should Know

2 de janeiro de 2026 · 10 min para ler

Mike Thrift

Marketing Manager

Beancount's power lies not just in its plain-text format, but in its extensibility through plugins. Native plugins are built-in modules that enhance Beancount's functionality, automate tedious tasks, and enforce accounting best practices. In this comprehensive guide, we'll explore all the native plugins available in Beancount and how to use them effectively.

What Are Beancount Plugins?

Beancount plugins are Python modules that process your ledger entries to add automation, validation, or transformation capabilities. They run during the loading phase of your ledger file and can:

Automate repetitive tasks (e.g., creating account declarations)
Validate data integrity (e.g., checking for duplicate transactions)
Transform entries (e.g., generating price entries from transactions)
Enforce accounting rules (e.g., one commodity per account)

How to Use Plugins

To enable a plugin in your Beancount file, add a plugin directive at the top of your ledger:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Some plugins accept configuration options:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

Native Plugin Categories

Beancount's native plugins fall into four main categories:

1. Automation Plugins

2. Validation Plugins

3. Transformation Plugins

4. Meta-Plugins

1. Automation Plugins

These plugins automate repetitive bookkeeping tasks, saving you time and reducing manual errors.

`auto_accounts` - Automatic Account Declarations

What it does: Automatically inserts Open directives for accounts that appear in transactions but haven't been explicitly declared.

Why use it: Eliminates the need to manually declare every account before using it. Perfect for getting started quickly or for users who prefer minimal boilerplate.

Example:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Without the plugin, you'd need to manually add:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

When to use: Ideal for beginners or those who want a less verbose ledger. However, explicit account declarations can help catch typos.

`close_tree` - Automatic Account Hierarchy Closing

What it does: When you close a parent account, this plugin automatically closes all its descendant accounts.

Why use it: Maintains consistency in your account hierarchy. If you close Assets:Investments, all sub-accounts like Assets:Investments:Stocks and Assets:Investments:Bonds will be closed automatically.

Example:

plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; These will be automatically closed:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

When to use: When restructuring your account hierarchy or closing entire categories of accounts.

`implicit_prices` - Automatic Price Entry Generation

What it does: Synthesizes Price directives from transaction postings that include costs (@) or prices (@@).

Why use it: Populates your price database automatically from your transactions, enabling accurate market value reporting without manual price entries.

Example:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

This automatically generates:

2026-01-02 price AAPL  150.00 USD

When to use: Essential for investment tracking and multi-currency accounting where you want automatic price history.

2. Validation Plugins

These plugins enforce data integrity and accounting best practices, catching errors before they become problems.

`noduplicates` - Duplicate Transaction Detection

What it does: Checks that no two transactions are identical by computing and comparing hashes of transaction data.

Why use it: Prevents accidental duplicate entries, especially when importing transactions from multiple sources.

Example:

plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; This would trigger an error:
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

When to use: Always recommended, especially if you're importing from bank statements or using multiple data sources.

`check_commodity` - Commodity Declaration Validation

What it does: Ensures all commodities used in your ledger have corresponding Commodity directives.

Why use it: Enforces explicit commodity declarations, helping you maintain a clean list of assets and currencies.

Example:

plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; This would trigger an error without a commodity declaration:
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

When to use: Recommended for maintaining strict commodity tracking and preventing typos in ticker symbols.

`check_average_cost` - Cost Basis Validation

What it does: Verifies that cost basis is properly preserved in transactions, especially when using average-cost booking.

Why use it: Ensures your cost accounting remains accurate for tax reporting and capital gains calculations.

When to use: Critical for investment portfolios and any scenario where accurate cost tracking matters.

`check_closing` - Balance Closing Validation

What it does: Expands the closing metadata into balance checks, ensuring positions are zero after closing trades.

Why use it: Confirms that when you sell an entire position, the balance is truly zero (no fractional shares remaining).

Example:

plugin "beancount.plugins.check_closing"

2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15000.00 USD
  Income:Investments:Gains   -500.00 USD

The #closing tag tells the plugin to verify that your AAPL position is zero after this transaction.

When to use: When selling entire positions to ensure nothing is left behind.

`coherent_cost` - Currency/Cost Consistency Check

What it does: Validates that currencies aren't used inconsistently — both with and without cost annotations.

Why use it: Prevents mixing bare currencies (like 100 USD) with costed currencies (like 100 USD {1.2 CAD}), which can cause accounting errors.

When to use: Recommended for multi-currency ledgers to maintain consistency.

`leafonly` - Leaf Account Enforcement

What it does: Ensures that only leaf accounts (accounts with no children) receive postings.

Why use it: Enforces a clean account hierarchy where summary accounts like Expenses:Food don't have direct postings, only their children like Expenses:Food:Groceries and Expenses:Food:Restaurants.

Example:

plugin "beancount.plugins.leafonly"

; This would trigger an error:
2026-01-02 * "Grocery shopping"
  Expenses:Food              50.00 USD  ; Error: Should post to a leaf account
  Assets:Cash               -50.00 USD

; Correct way:
2026-01-02 * "Grocery shopping"
  Expenses:Food:Groceries    50.00 USD  ; Correct: Posting to leaf account
  Assets:Cash               -50.00 USD

When to use: When you want to maintain strict hierarchical accounting with clear categorization.

`nounused` - Unused Account Detection

What it does: Identifies accounts that were opened but never actually used in any transactions.

Why use it: Helps you clean up your account declarations and identify potential typos or abandoned accounts.

When to use: Periodically, to audit and clean up your account structure.

`onecommodity` - Single Commodity Per Account

What it does: Enforces that each account holds only one type of commodity.

Why use it: Prevents mixing different assets in the same account, which is generally an accounting best practice.

Example:

plugin "beancount.plugins.onecommodity"

2026-01-02 * "Buy stocks"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD

; This would trigger an error:
2026-01-03 * "Buy more stocks"
  Assets:Investments         5 GOOGL @ 140 USD  ; Error: Different commodity
  Assets:Cash              -700.00 USD

When to use: When you prefer strict account separation (one account per stock/asset).

`sellgains` - Capital Gains Validation

What it does: Cross-checks declared capital gains against the computed gains from lot sales, ensuring your profit/loss calculations are accurate.

Why use it: Catches errors in manual capital gains calculations, critical for accurate tax reporting.

Example:

plugin "beancount.plugins.sellgains"

2026-01-02 * "Sell AAPL shares"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Plugin validates this is correct

The plugin will verify: Sale proceeds (1500) - Cost basis (1400) = Gains (100)

When to use: Essential for anyone trading stocks, crypto, or other assets where capital gains matter.

`unique_prices` - Price Uniqueness Check

What it does: Ensures there's only one price entry per commodity per date.

Why use it: Prevents conflicting price data that could lead to incorrect valuations.

When to use: Recommended when manually entering prices or importing from multiple price sources.

3. Transformation Plugins

These plugins modify or enhance your ledger data in useful ways.

`currency_accounts` - Currency Trading Accounts

What it does: Implements currency trading accounts for tracking forex conversions explicitly.

Why use it: Provides detailed tracking of currency conversion transactions, useful for accounting standards that require it.

When to use: When you need to track forex gains/losses separately or meet specific accounting requirements.

`commodity_attr` - Commodity Attribute Validation

What it does: Validates that commodity directives have required attributes (like export, name, etc.).

Why use it: Ensures your commodity metadata is complete and consistent.

When to use: When you maintain detailed commodity metadata for reporting or export purposes.

4. Meta-Plugins

These plugins are collections of other plugins for convenience.

`auto` - All Automatic Plugins

What it does: Enables a collection of "lax" or automatic plugins in one directive.

When to use: Quick setup for users who want maximum automation with minimal configuration.

`pedantic` - All Validation Plugins

What it does: Enables all strict validation plugins at once.

Why use it: Enforces maximum data integrity and accounting rigor. Great for production ledgers or when accuracy is paramount.

Example:

plugin "beancount.plugins.pedantic"

; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

When to use: For production ledgers where you want maximum validation and are willing to maintain stricter accounting practices.

Recommended Plugin Configurations

For Beginners

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

This minimal set provides automation while preventing common errors.

For Investors

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Focuses on investment tracking and capital gains accuracy.

For Strict Accounting

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Maximum validation for production environments.

Default Configuration at Beancount.io

At Beancount.io, we include the auto_accounts plugin by default in all new ledger files:

plugin "beancount.plugins.auto_accounts"

This provides a great balance between ease of use and functionality for getting started quickly.

Best Practices

Start minimal, add as needed: Begin with auto_accounts and noduplicates, then add validation plugins as your ledger matures.
Test plugins individually: When adding multiple plugins, enable them one at a time to understand their effects.
Read error messages carefully: Plugin errors often point to real accounting issues that need fixing.
Use pedantic for production: Once your workflow is established, consider enabling strict validation.
Combine with custom plugins: Native plugins work alongside custom plugins like the forecast plugin for maximum functionality.

Beyond Native Plugins

While native plugins provide core functionality, the Beancount ecosystem includes many community-developed plugins for specialized needs:

fava.plugins.forecast - For recurring transaction forecasting
fava.plugins.link_documents - For linking transactions to receipt files
Custom importers for bank-specific CSV formats
Tax-specific calculators and reports

Explore the Beancount ecosystem for more options.

Conclusion

Beancount's native plugins transform plain-text accounting from a manual process into an automated, validated, and robust financial management system. By understanding and leveraging these built-in tools, you can:

✅ Automate tedious bookkeeping tasks
✅ Catch errors before they become problems
✅ Maintain strict data integrity
✅ Generate accurate financial reports
✅ Focus on financial insights rather than data entry

Start experimenting with these plugins in your ledger today. Begin with auto_accounts and implicit_prices, then gradually add validation plugins as your accounting practices mature.

Ready to try these plugins? Head over to Beancount.io and start using them in your ledger file today!

Sources

Have questions about Beancount plugins? Join the discussion on our community forum or check out our documentation.

References:

Share on Twitter Follow @beancount_io

What Are Beancount Plugins?​

How to Use Plugins​

Native Plugin Categories​

1. Automation Plugins​

2. Validation Plugins​

3. Transformation Plugins​

4. Meta-Plugins​

1. Automation Plugins​

auto_accounts - Automatic Account Declarations​

close_tree - Automatic Account Hierarchy Closing​

implicit_prices - Automatic Price Entry Generation​

2. Validation Plugins​

noduplicates - Duplicate Transaction Detection​

check_commodity - Commodity Declaration Validation​

check_average_cost - Cost Basis Validation​

check_closing - Balance Closing Validation​

coherent_cost - Currency/Cost Consistency Check​

leafonly - Leaf Account Enforcement​

nounused - Unused Account Detection​

onecommodity - Single Commodity Per Account​

sellgains - Capital Gains Validation​

unique_prices - Price Uniqueness Check​

3. Transformation Plugins​

currency_accounts - Currency Trading Accounts​

commodity_attr - Commodity Attribute Validation​

4. Meta-Plugins​

auto - All Automatic Plugins​

pedantic - All Validation Plugins​

Recommended Plugin Configurations​

For Beginners​

For Investors​

For Strict Accounting​

Default Configuration at Beancount.io​

Best Practices​

Beyond Native Plugins​

Conclusion​

Sources​

Comece a usar o Beancount.io

Primeiros Passos

Recursos

Comunidade

Jurídico

What Are Beancount Plugins?

How to Use Plugins

Native Plugin Categories

1. Automation Plugins

2. Validation Plugins

3. Transformation Plugins

4. Meta-Plugins

1. Automation Plugins

`auto_accounts` - Automatic Account Declarations

`close_tree` - Automatic Account Hierarchy Closing

`implicit_prices` - Automatic Price Entry Generation

2. Validation Plugins

`noduplicates` - Duplicate Transaction Detection

`check_commodity` - Commodity Declaration Validation

`check_average_cost` - Cost Basis Validation

`check_closing` - Balance Closing Validation

`coherent_cost` - Currency/Cost Consistency Check

`leafonly` - Leaf Account Enforcement

`nounused` - Unused Account Detection

`onecommodity` - Single Commodity Per Account

`sellgains` - Capital Gains Validation

`unique_prices` - Price Uniqueness Check

3. Transformation Plugins

`currency_accounts` - Currency Trading Accounts

`commodity_attr` - Commodity Attribute Validation

4. Meta-Plugins

`auto` - All Automatic Plugins

`pedantic` - All Validation Plugins

Recommended Plugin Configurations

For Beginners

For Investors

For Strict Accounting

Default Configuration at Beancount.io

Best Practices

Beyond Native Plugins

Conclusion

Sources