Основные встроенные плагины Beancount, которые вам стоит знать

Актуально на 2026-09-15.

Сила Beancount заключается не только в его формате открытого текста, но и в расширяемости через плагины. Встроенные плагины — это встроенные модули, которые расширяют функциональность Beancount, автоматизируют утомительные задачи и обеспечивают соблюдение лучших практик бухгалтерского учета. В этом подробном руководстве мы рассмотрим все встроенные плагины, доступные в Beancount, и как эффективно их использовать.

Синтаксис директив, с которыми работают эти плагины, описан в справочнике по синтаксису Beancount. Реальные примеры рабочих процессов сообщества, сочетающих плагины с импортерами и Fava, смотрите в витрине сообщества. Параметры журнала, взаимодействующие с плагинами, описаны в конфигурации параметров.

Что такое плагины Beancount?​

Плагины Beancount — это модули Python, которые обрабатывают записи вашего журнала для добавления возможностей автоматизации, проверки или преобразования. Они запускаются на этапе загрузки вашего файла журнала и могут:

• Автоматизировать повторяющиеся задачи (например, создание объявлений счетов)
• Проверять целостность данных (например, проверку на дубликаты транзакций)
• Преобразовывать записи (например, генерировать записи цен из транзакций)
• Обеспечивать соблюдение правил бухгалтерского учета (например, одна валюта на счет)

Как использовать плагины​

Чтобы включить плагин в вашем файле Beancount, добавьте директиву plugin в начало вашего журнала:

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

Некоторые плагины принимают параметры конфигурации:

; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"

Категории встроенных плагинов​

Встроенные плагины Beancount делятся на четыре основные категории:

1. Плагины автоматизации​

2. Плагины проверки​

3. Плагины преобразования​

4. Мета-плагины​

1. Плагины автоматизации​

Эти плагины автоматизируют повторяющиеся задачи бухгалтерского учета, экономя ваше время и уменьшая количество ручных ошибок.

auto_accounts — Автоматические объявления счетов​

Что делает: Автоматически вставляет директивы Open для счетов, которые появляются в транзакциях, но не были явно объявлены.

Зачем использовать: Устраняет необходимость вручную объявлять каждый счет перед его использованием. Идеально подходит для быстрого начала работы или для пользователей, предпочитающих минимальный шаблонный код.

Пример:

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Без плагина вам пришлось бы вручную добавить:

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

Когда использовать: Идеально для новичков или тех, кто хочет менее подробный журнал. Однако явные объявления счетов могут помочь выявить опечатки.

close_tree — Автоматическое закрытие иерархии счетов​

Что делает: Когда вы закрываете родительский счет, этот плагин автоматически закрывает все его дочерние счета.

Зачем использовать: Поддерживает согласованность в иерархии ваших счетов. Если вы закроете Assets:Investments, все под-счета, такие как Assets:Investments:Stocks и Assets:Investments:Bonds, будут закрыты автоматически.

Пример:

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

Когда использовать: При реструктуризации иерархии счетов или закрытии целых категорий счетов.

implicit_prices — Автоматическая генерация записей цен​

Что делает: Создает директивы Price из проводок транзакций, которые включают стоимость (@) или цены (@@).

Зачем использовать: Автоматически заполняет вашу базу цен из транзакций, обеспечивая точную отчетность о рыночной стоимости без ручного ввода цен.

Пример:

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Это автоматически генерирует:

2026-01-02 price AAPL  150.00 USD

Когда использовать: Необходимо для отслеживания инвестиций и многовалютного учета, где требуется автоматическая история цен.

2. Плагины проверки​

Эти плагины обеспечивают целостность данных и соблюдение лучших практик бухгалтерского учета, выявляя ошибки до того, как они станут проблемами.

noduplicates — Обнаружение дублирующихся транзакций​

Что делает: Проверяет, что никакие две транзакции не идентичны, вычисляя и сравнивая хэши данных транзакций.

Зачем использовать: Предотвращает случайные дублирующиеся записи, особенно при импорте транзакций из нескольких источников.

Пример:

; @m49-fragment expected-failure
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

Когда использовать: Всегда рекомендуется, особенно если вы импортируете из банковских выписок или используете несколько источников данных.

check_commodity — Проверка объявления товаров​

Что делает: Гарантирует, что все товары, используемые в вашем журнале, имеют соответствующие директивы Commodity.

Зачем использовать: Обеспечивает явные объявления товаров, помогая поддерживать чистый список активов и валют.

Пример:

; @m49-fragment expected-failure
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

Когда использовать: Рекомендуется для поддержания строгого отслеживания товаров и предотвращения опечаток в тикерах.

check_average_cost — Проверка себестоимости​

Что делает: Проверяет, что себестоимость правильно сохраняется в транзакциях, особенно при использовании метода средней стоимости.

Зачем использовать: Гарантирует точность вашего учета затрат для налоговой отчетности и расчета прироста капитала.

Когда использовать: Критически важно для инвестиционных портфелей и любых сценариев, где важна точность отслеживания затрат.

check_closing — Проверка закрытия баланса​

Что делает: Разворачивает метаданные closing в проверки баланса, гарантируя нулевые позиции после закрытия сделок.

Зачем использовать: Подтверждает, что при продаже всей позиции баланс действительно равен нулю (не остается дробных акций).

Пример:

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.00 USD
  Income:Investments:Gains    -500.00 USD

Тег #closing сообщает плагину, что нужно проверить, что ваша позиция AAPL равна нулю после этой транзакции.

Когда использовать: При продаже целых позиций, чтобы убедиться, что ничего не осталось.

coherent_cost — Проверка согласованности валюты/себестоимости​

Что делает: Проверяет, что валюты не используются непоследовательно — как с аннотациями себестоимости, так и без них.

Зачем использовать: Предотвращает смешивание простых валют (например, 100 USD) с валютами с себестоимостью (например, 100 USD {1.2 CAD}), что может вызвать ошибки в учете.

Когда использовать: Рекомендуется для многовалютных журналов для поддержания согласованности.

leafonly — Обеспечение учета только на листовых счетах​

Что делает: Гарантирует, что только листовые счета (счета без дочерних) получают проводки.

Зачем использовать: Обеспечивает чистую иерархию счетов, где сводные счета, такие как Expenses:Food, не имеют прямых проводок, а только их дочерние счета, такие как Expenses:Food:Groceries и Expenses:Food:Restaurants.

Пример:

; @m49-fragment expected-failure
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

Когда использовать: Когда вы хотите поддерживать строгий иерархический учет с четкой категоризацией.

nounused — Обнаружение неиспользуемых счетов​

Что делает: Определяет счета, которые были открыты, но никогда фактически не использовались в транзакциях.

Зачем использовать: Помогает очистить объявления счетов и выявить возможные опечатки или заброшенные счета.

Когда использовать: Периодически, для аудита и очистки структуры счетов.

onecommodity — Один товар на счет​

Что делает: Обеспечивает, что каждый счет содержит только один тип товара.

Зачем использовать: Предотвращает смешивание разных активов на одном счете, что обычно является лучшей практикой бухгалтерского учета.

Пример:

; @m49-fragment expected-failure
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

Когда использовать: Когда вы предпочитаете строгое разделение счетов (один счет на акцию/актив).

sellgains — Проверка прироста капитала​

Что делает: Сверяет заявленный прирост капитала с рассчитанным приростом от продажи лотов, гарантируя точность расчетов прибыли/убытков.

Зачем использовать: Выявляет ошибки в ручных расчетах прироста капитала, что критически важно для точной налоговой отчетности.

Пример:

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

Плагин проверит: Выручка от продажи (1500) - Себестоимость (1400) = Прибыль (100)

Когда использовать: Необходимо для тех, кто торгует акциями, криптовалютой или другими активами, где важен прирост капитала.

unique_prices — Проверка уникальности цен​

Что делает: Гарантирует, что существует только одна запись цены на товар на дату.

Зачем использовать: Предотвращает конфликтующие данные о ценах, которые могут привести к неправильной оценке.

Когда использовать: Рекомендуется при ручном вводе цен или импорте из нескольких источников цен.

check_drained — Проверка опустошенных счетов​

Что делает: Помечает счета, на которых все еще есть баланс (включая неоцененные валюты или остаточные лоты), когда вы ожидали, что они будут пустыми после переводов или закрытий.

Зачем использовать: Выявляет остаточные балансы, которые могут пропустить проверки balance и теги #closing — особенно полезно после переводов с несколькими товарами.

Статус (проверено 2026-09-15): Присутствует в дереве Beancount 3.x по адресу beancount/plugins/check_drained.py на текущей линии PyPI (3.2.3).

Когда использовать: После крупных реорганизаций портфеля или при закрытии брокерских счетов.

3. Плагины преобразования​

Эти плагины полезным образом изменяют или улучшают данные вашего журнала.

currency_accounts — Счета для торговли валютами​

Что делает: Реализует счета для торговли валютами для явного отслеживания конверсий валют.

Зачем использовать: Обеспечивает детальное отслеживание операций по конвертации валют, что полезно для стандартов бухгалтерского учета, требующих этого.

Когда использовать: Когда вам нужно отслеживать прибыли/убытки от операций с валютой отдельно или соответствовать конкретным требованиям бухгалтерского учета.

commodity_attr — Проверка атрибутов товаров​

Что делает: Проверяет, что директивы товаров имеют необходимые атрибуты (такие как export, name и т.д.).

Зачем использовать: Обеспечивает полноту и согласованность метаданных товаров.

Когда использовать: Когда вы ведете подробные метаданные товаров для отчетности или экспорта.

4. Мета-плагины​

Эти плагины представляют собой наборы других плагинов для удобства.

auto — Все автоматические плагины​

Что делает: Включает набор «мягких» или автоматических плагинов одной директивой.

Когда использовать: Быстрая настройка для пользователей, которые хотят максимальной автоматизации с минимальной конфигурацией.

pedantic — Все плагины проверки​

Что делает: Включает все строгие плагины проверки одновременно.

Зачем использовать: Обеспечивает максимальную целостность данных и строгость бухгалтерского учета. Отлично подходит для производственных журналов или когда точность имеет первостепенное значение.

Пример:

plugin "beancount.plugins.pedantic"
 
; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Когда использовать: Для производственных журналов, где требуется максимальная проверка и вы готовы соблюдать более строгие методы учета.

Рекомендуемые конфигурации плагинов​

Для новичков​

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

Этот минимальный набор обеспечивает автоматизацию и предотвращает распространенные ошибки.

Для инвесторов​

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"

Сосредоточен на отслеживании инвестиций и точности прироста капитала.

Для строгого бухгалтерского учета​

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

Максимальная проверка для производственных сред.

Конфигурация по умолчанию на Beancount.io​

На Beancount.io мы включаем плагин auto_accounts по умолчанию во все новые файлы журналов:

plugin "beancount.plugins.auto_accounts"

Это обеспечивает отличный баланс между простотой использования и функциональностью для быстрого начала работы.

Статус плагинов проверен 2026-09-15​

Сравнение с текущим деревом beancount/plugins на Beancount 3.2.3 (PyPI, 2026-09-15):

Ничего из этого встроенного набора не было удалено между первоначальным черновиком этого руководства и указанной выше датой. Плагины сообщества (не встроенные) по-прежнему относятся к списку плагинов Awesome Beancount и в витрину сообщества — относитесь к сторонним репозиториям как к независимо версионируемым и проверяйте дату последнего релиза каждого репозитория перед включением в производственный журнал.

Лучшие практики​

1. Начинайте с минимума, добавляйте по мере необходимости: Начните с auto_accounts и noduplicates, затем добавляйте плагины проверки по мере развития вашего журнала.

2. Тестируйте плагины по отдельности: При добавлении нескольких плагинов включайте их по одному, чтобы понять их влияние.

3. Внимательно читайте сообщения об ошибках: Ошибки плагинов часто указывают на реальные проблемы в бухгалтерском учете, которые необходимо исправить.

4. Используйте pedantic для производства: После того как ваш процесс установлен, рассмотрите возможность включения строгой проверки.

5. Комбинируйте с пользовательскими плагинами: Встроенные плагины работают вместе с пользовательскими плагинами, такими как плагин forecast, для максимальной функциональности.

За пределами встроенных плагинов​

Хотя встроенные плагины обеспечивают основную функциональность, экосистема Beancount включает множество плагинов, разработанных сообществом, для специализированных нужд:

• fava.plugins.forecast — Для прогнозирования повторяющихся транзакций
• fava.plugins.link_documents — Для связывания транзакций с файлами чеков
• Пользовательские импортеры для банковских CSV-форматов
• Специализированные калькуляторы и отчеты по налогам

Изучите экосистему Beancount для получения дополнительных вариантов и витрину сообщества для примеров того, как люди сочетают встроенные плагины с импортерами и Fava.

Заключение​

Встроенные плагины Beancount превращают учет в открытом тексте из ручного процесса в автоматизированную, проверенную и надежную систему управления финансами. Понимая и используя эти встроенные инструменты, вы можете:

• ✅ Автоматизировать утомительные задачи бухгалтерского учета
• ✅ Выявлять ошибки до того, как они станут проблемами
• ✅ Поддерживать строгую целостность данных
• ✅ Создавать точные финансовые отчеты
• ✅ Сосредоточиться на финансовых идеях, а не на вводе данных

Начните экспериментировать с этими плагинами в своем журнале уже сегодня. Начните с auto_accounts и implicit_prices, затем постепенно добавляйте плагины проверки по мере развития ваших методов учета.

Готовы попробовать эти плагины? Зайдите на Beancount.io и начните использовать их в своем файле журнала уже сегодня!

Источники​

• Справочник по API плагинов Beancount
• Руководство по скриптам и плагинам Beancount
• Плагины и параметры Beancount от Брайана Алвеса
• Репозиторий Beancount на GitHub

Есть вопросы о плагинах Beancount? Присоединяйтесь к обсуждению на нашем форуме сообщества или ознакомьтесь с нашей документацией.

Изучите живой пример журнала криптовалют: