Основні вбудовані плагіни 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 * "Кав'ярня"
  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
 
; Ці буде автоматично закрито:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Коли використовувати: під час реструктуризації ієрархії рахунків або закриття цілих категорій рахунків.

implicit_prices — автоматичне створення записів цін​

Що робить: створює директиви Price із проводок транзакцій, які містять вартість (@) або ціну (@@).

Навіщо використовувати: автоматично наповнює вашу базу цін із транзакцій, забезпечуючи точну звітність про ринкову вартість без ручного введення цін.

Приклад:

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Купівля акцій AAPL"
  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 * "Оплата оренди"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; Це спричинить помилку:
2026-01-02 * "Оплата оренди"
  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
 
; Це спричинить помилку без оголошення товару:
2026-01-02 * "Купівля біткоїна"
  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 * "Закриття всієї позиції AAPL" #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"
 
; Це спричинить помилку:
2026-01-02 * "Закупівля продуктів"
  Expenses:Food              50.00 USD  ; Помилка: слід проводити на листовий рахунок
  Assets:Cash               -50.00 USD
 
; Правильний спосіб:
2026-01-02 * "Закупівля продуктів"
  Expenses:Food:Groceries    50.00 USD  ; Правильно: проводка на листовий рахунок
  Assets:Cash               -50.00 USD

Коли використовувати: коли ви хочете підтримувати сувору ієрархічну структуру обліку з чіткою категоризацією.

nounused — виявлення невикористаних рахунків​

Що робить: визначає рахунки, які були відкриті, але ніколи фактично не використовувалися в жодних транзакціях.

Навіщо використовувати: допомагає очистити ваші оголошення рахунків і виявити потенційні помилки друку або занедбані рахунки.

Коли використовувати: періодично, для аудиту та очищення структури рахунків.

onecommodity — один товар на рахунок​

Що робить: забезпечує, що кожен рахунок містить лише один тип товару.

Навіщо використовувати: запобігає змішуванню різних активів в одному рахунку, що загалом є найкращою практикою обліку.

Приклад:

; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "Купівля акцій"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; Це спричинить помилку:
2026-01-03 * "Купівля більше акцій"
  Assets:Investments         5 GOOGL @ 140 USD  ; Помилка: інший товар
  Assets:Cash              -700.00 USD

Коли використовувати: коли ви віддаєте перевагу суворому розділенню рахунків (один рахунок на акцію/актив).

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

Що робить: звіряє задекларований приріст капіталу з обчисленим приростом від продажу партій, забезпечуючи точність розрахунків прибутків і збитків.

Навіщо використовувати: виявляє помилки в ручних розрахунках приросту капіталу, що критично важливо для точної податкової звітності.

Приклад:

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "Продаж акцій AAPL"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Плагін перевіряє, що це правильно

Плагін перевірить: виручка від продажу (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"
 
; Це еквівалентно увімкненню:
; - 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. Поєднуйте з власними плагінами: вбудовані плагіни працюють разом із власними плагінами, як-от плагін прогнозування, для максимальної функціональності.

За межами вбудованих плагінів​

Хоча вбудовані плагіни забезпечують основну функціональність, екосистема 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? Приєднуйтеся до обговорення на нашому форумі спільноти або перегляньте нашу документацію.

Дослідіть живий приклад криптовалютного реєстру: