Перейти до основного вмісту

Конфігурація параметрів

Дізнайтеся, як налаштувати поведінку Beancount за допомогою директив опцій, забезпечуючи відповідність вашої системи бухгалтерського обліку вашим конкретним потребам. Цей посібник охоплює основні опції конфігурації, необхідні для ефективного управління бухгалтерською книгою.

Поведінка Beancount налаштовується директивами option, які розміщуються у верхній частині вашого основного файлу бухгалтерської книги. Ці пари ключ-значення контролюють назви кореневих рахунків, наскільки велика може бути дисбаланс у транзакції та які розширення запускаються. ⚙️

Кожна опція на цій сторінці була перевірена на Beancount 3.2.3, і кожне наведене повідомлення про помилку є тим, що друкує ця версія. Beancount відхиляє опцію, яку він не розпізнає — option "default_tolerance" "USD:0.01" помилково відкликається з Invalid option: 'default_tolerance' — тож опція, скопійована зі старішого посібника, не призведе до мовчазної помилки. Запускайте bea check на вашому файлі після будь-яких змін тут.

Основні параметри конфігурації​

Ці опції контролюють фундаментальні налаштування вашої бухгалтерської книги.

Базові налаштування​

Це одні з найпоширеніших параметрів, які ви встановите.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"
  • title: Встановлює заголовок для звітів і веб-інтерфейсів. За замовчуванням Beancount.
  • render_commas: Якщо істинно, числа у звітах форматуються з тисячними роздільниками (наприклад, 1,000,000.00). За замовчуванням — хибне. Будь-яке з 1, TRUE, true, або yes читається як істина; будь-який інший рядок — як хибність.
  • plugin_processing_mode: або default (за замовчуванням), або raw. Будь-яке інше значення викликає помилку Error for option 'plugin_processing_mode'.

raw — не м’якша версія default, це перемикач, який відключає власні стадії обробки Beancount. У режимі default Beancount запускає beancount.ops.documents перед плагінами, а beancount.ops.pad і beancount.ops.balance після них. У режимі raw він запускає лише плагіни, які ви вказали самі, тож директиви pad ніколи не застосовуються, а перевірки balance ніколи не виконуються:

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

Змініть цей рядок на default, і той самий файл повідомить Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Використовуйте raw лише якщо свідомо реалізуєте ці стадії самостійно.

Налаштування назв рахунків​

Ви можете перейменувати п’ять фундаментальних типів рахунків Beancount. Це не косметично. Опція перепризначає кореневі назви, які парсер приймає, тому кожен рахунок у вашому файлі має використовувати нову назву, а стара стає недійсною.

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

Залишене одне проведення зі старим коренем призведе до неможливості завантаження файлу з повідомленням Invalid account name: Assets:Banque:Courant. П’ять опцій — це name_assets, name_liabilities, name_equity, name_income та name_expenses; кожне значення має бути одним словом з великої літери без двокрапки, інакше виникає помилка Error for option 'name_assets': Invalid root account name. Перейменовуйте корені на початку ведення книги, а не посередині.

Конфігурація рахунку капіталу (власного капіталу)​

Beancount синтезує декілька рахунків капіталу при підсумовуванні періоду — початкові баланси, нерозподілений прибуток та конверсії валют. Ці опції задають їхні назви.

Кожне значення — це ім'я листа, і Beancount поєднує його під name_equity для вас. Записування кореня капіталу власноруч дає Equity:Equity:Opening-Balances — це вже інший рахунок, ніж той, який ви хотіли.

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"
ОпціяНазва листа за замовчуваннямРахунок, що утворюється
account_previous_balancesOpening-BalancesEquity:Opening-Balances
account_previous_earningsEarnings:PreviousEquity:Earnings:Previous
account_current_earningsEarnings:CurrentEquity:Earnings:Current
account_previous_conversionsConversions:PreviousEquity:Conversions:Previous
account_current_conversionsConversions:CurrentEquity:Conversions:Current

Вийнятком у цій групі є account_rounding: ця опція приймає повну назву рахунку і зберігається точно як записано, тому Equity:Rounding в наведеному прикладі є правильним і не має подвоєного префікса. Вона також не встановлена за замовчуванням, і в Beancount 3.2.3 її встановлення не впливає на завантаження — див. Точність і допуски для того, що насправді відбувається із залишками.

Налаштування Точності та Допусків​

Ці опції контролюють, який дисбаланс Beancount приймає у транзакції.

Конфігурація стандартного допуску​

Beancount виводить допуск для кожної транзакції, ґрунтуючись на кількості десяткових знаків у проводках. Ці три опції налаштовують це виведення.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"
  • inferred_tolerance_default: мінімальний допуск на валюту, використовується, коли в транзакції немає десяткових знаків для виведення. Синтаксис: <валюта>:<число>, * задає всім валютам одночасно. Опцію можна повторювати для кількох валют.
  • tolerance_multiplier: частка найменшої цифри, що вважається припустимою, за замовчуванням 0.5. Це не відсоткове збільшення: 1.2 подвоює кожен виведений допуск у 2,4 рази від стандартного.
  • infer_tolerance_from_cost: якщо істинно, проводки за собівартістю розширюють допуск у валюті собівартості також. За замовчуванням вимкнено.

Стара назва inferred_tolerance_multiplier все ще задає те ж значення, але викликає помилку завантаження із повідомленням Renamed to 'tolerance_multiplier'., тому bea check не проходить з файлом, який її використовує. Переіменуйте.

Метод бронювання (booking method)​

Ця опція задає правило за замовчуванням для вибору лота, з якого списується зменшення. Для одного рахунку можна задати окреме правило в директиві open.

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 приймає рівно сім назв: STRICT (за замовчуванням), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO і AVERAGE. Будь-яке інше значення відхиляється при завантаженні з помилкою Error for option 'booking_method' — це включає SIMPLE і FULL, які не є методами бронювання і ніколи ними не були. AVERAGE приймається, але не реалізований; спроба зробити списання цим методом викликає помилку AVERAGE method is not supported. Управління запасами працює зі всіма сімома на одній книзі.

Валютне управління​

Правильна конфігурація валют надзвичайно важлива для точних звітів.

Оперативна валюта​

Оперативна валюта — це валюта, у якій ви хочете підсумовувати звіти. Опція повторюється для оголошення кількох валют; значення накопичуються, а не замінюють одне одного.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Оголошення оперативних валют інструктує звітні інструменти формувати для кожної власну колонку. conversion_currency дає ім'я уявній валюті, в якій Beancount веде облік конверсій за курсом нуль; за замовчуванням це NOTHING, і єдина причина змінити її — вибрати інший заповнювач, який у вашій книзі ніколи не використовується як реальний товар.

Управління документами​

Beancount може пов'язувати транзакції з зовнішніми файлами, як чек або накладна. Опція documents задає папку для сканування.

option "documents" "/home/user/Documents/beancount"

Шлях у цьому блоці ілюстративний — замініть його на свій перед запуском. Тільки перше правило нижче викликає повідомлення про помилку; порушення інших призводить лише до того, що файл не знаходиться:

  • Папка має існувати. Відсутність викликає помилку Document root '/no/such/place' does not exist.
  • Підпапки — це назви рахунків. Виписка для Assets:US:BofA:Checking має бути в <root>/Assets/US/BofA/Checking/. Файли, що лежать безпосередньо в корені, ігноруються.
  • Рахунок має бути відкритий. Документи, знайдені під рахунком, який не відкривається у вашій книзі, ігноруються без попередження.
  • Імена файлів починаються з дати у форматі YYYY-MM-DD.description.ext (наприклад, 2025-07-28.amazon-order.pdf). Все інше в папці ігнорується.
  • Шляхи можуть бути абсолютними або відносними до основного файлу книги; опцію можна повторювати для кількох папок.

Система плагінів​

Функціональність Beancount можна розширювати за допомогою плагінів.

Конфігурація плагінів​

Плагін завантажується окремою директивою plugin, а не option. option "plugin" "..." викликає помилку Option 'plugin' may not be set.

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

Файл завантажується, бо auto_accounts відкриває обидва рахунки для вас; видаліть рядок plugin, і він скаже Invalid reference to unknown account 'Expenses:Food:Coffee'. Плагін, який приймає конфігурацію, отримує її як другий рядок, plugin "module" "config". Плагіни виконуються в порядку, в якому ви їх вказали, після власної стадії documents Beancount і перед pad та balance, якщо не встановлено plugin_processing_mode у raw, що відміняє ці стадії зовсім.

Технічні обмеження та ліміти​

Ці опції контролюють технічні аспекти парсера Beancount.

Обробка рядків​

Ви можете встановити обмеження на кількість рядків у багаторядковому рядку, щоб незавершена лапка викликала повідомлення про помилку ближче до того місця, де ви її ввели, а не в кінці файлу.

option "long_string_maxlines" "64"

Точність інтерполяції​

За замовчуванням Beancount використовує один допуск для двох різних цілей: заповнення відсутньої суми і визначення, чи збалансована транзакція. Увімкнення цієї опції використовує найточніший виведений допуск для першої задачі і найвільніший для другої, що запобігає дрейфу інтерпольованих сум.

option "use_precise_interpolation" "TRUE"

Опції для явних допусків на проводку немає. Єдиний явний синтаксис допусків у Beancount 3.2.3 — це тильда у директиві balance — 4.271 ~ 0.01 RGAGX — і вона не потребує опції. Тильда у середині проводки — синтаксична помилка.

Заборонені та видалені опції​

Три опції, які все ще рекомендують старі посібники, відсутні в Beancount 3.2.3. Кожен рядок із цього блоку викликає помилку завантаження:

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"
  • experiment_explicit_tolerances — синтаксис ~ на рівні проводки, який він включав, зник; використовуйте тильду директиви balance.
  • use_legacy_fixed_tolerances — фіксовані допуски 0.005/0.015 зникли; допуск визначається для кожної транзакції та настроюється tolerance_multiplier та inferred_tolerance_default.
  • default_tolerance — замінена на inferred_tolerance_default для балансування і display_precision для виводу.

Ще три досі працюють, але виводять помилку застарілості, чого достатньо для провалу bea check:

  • inferred_tolerance_multiplier — перейменована на tolerance_multiplier.
  • allow_pipe_separator — підтримує старий роздільник | між отримувачем і описом.
  • allow_deprecated_none_for_tags_and_links — підтримує буквальний None там, де мають бути теги і посилання.

Опції Fava є окремими​

Усе на цій сторінці читається самим Beancount. Налаштування Fava не є директивами option — це директиви custom "fava-option" з датою, і Beancount їх ігнорує. Запис опції Fava як option викликає помилку Invalid option. Див. Опції Fava для списку.

Рекомендована конфігурація ✅​

Для більшості користувачів наведена нижче конфігурація забезпечує надійну та розумну стартову точку. Це один файл, і він завантажується.

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

Коментарі починаються з ;. Коментар // — це синтаксична помилка в Beancount, яка відміняє весь файл.

Ця конфігурація забезпечує надійну основу для нової бухгалтерської книги Beancount, гарантуючи зрозумілі звіти, розумний контроль точності та логічну структуру рахунків капіталу.

Конфігурація параметрів

Джерело: https://beancount.io/uk/docs/Basics/options-configuration