Beancount v3: Що нового?

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

Beancount версії 3, випущена в середині 2024 року, ознаменувала значну архітектурну еволюцію популярного інструменту обліку в звичайному тексті. Хоча вона зберігає зворотну сумісність для файлів бухгалтерських книг користувачів, базова структура та супутні інструменти зазнали суттєвих змін. Ось огляд того, що нового в Beancount v3 — і що з'явилося в лінійці 3.1–3.2 з моменту першої публікації цього посібника.

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

Більш модульна та спрощена архітектура​

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

Ключові компоненти, які тепер є окремими пакетами, включають:

• beanquery: Потужний інструмент запитів у стилі SQL для ваших файлів бухгалтерських книг тепер у власному пакеті.
• beangulp: Це нове місце для фреймворку імпорту даних, що замінює колишній модуль beancount.ingest.
• beanprice: Окремий інструмент для отримання цін на товари та акції.

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

Зміни в інструментах командного рядка та робочих процесах​

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

• bean-report видалено: цей інструмент було вилучено. Тепер користувачам рекомендується використовувати bean-query (з пакета beanquery) для своїх потреб у звітності.
• Новий робочий процес імпортеру: команди bean-extract та bean-identify було вилучено з ядра. Новий підхід із beangulp базується на скриптах. Тепер користувачі створюватимуть власні Python-скрипти для обробки імпорту даних із зовнішніх джерел, таких як банківські виписки.

Покращення синтаксису та функцій​

Хоча основні принципи бухгалтерського обліку залишаються незмінними, Beancount v3 вносить деяку бажану гнучкість у свій синтаксис:

• Більш гнучкі коди валют: попередні обмеження на довжину та символи для назв валют було послаблено. Тепер підтримуються односимвольні символи валют.
• Розширені прапорці транзакцій: користувачі тепер можуть використовувати будь-яку велику літеру від A до Z як прапорець для транзакцій, що дозволяє більш детальну категоризацію.

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

Переписування на C++ та продуктивність​

Однією з довгострокових цілей Beancount було переписування компонентів, критичних для продуктивності, на C++. Початковий випуск Beancount v3 не включав ядро на C++, і станом на 2026-09-15 це залишається так: опублікована лінійка PyPI (через 3.2.3) все ще є модульною гілкою Python v3. Історична робота з C++/Bazel зберігається в окремій гілці cpp і не є частиною пакетів, які користувачі встановлюють із PyPI. Тому щоденна продуктивність поточних випусків v3 знаходиться в тому ж класі, що й пізні версії v2, з поступовими покращеннями парсера та інструментів, а не з переписуванням на C++ на порядок величин.

Після написання цього матеріалу (v3.1 → v3.2.x)​

Основні джерела: файл CHANGES проєкту, перегляди порівняння GitHub для 3.1.0…3.2.0 та PyPI beancount (остання версія 3.2.3 станом на 2026-09-15).

• Лінійка 3.1.x — Продовження очищення пакування та API після модульного розділення 3.0 (beanquery, beangulp, beanprice залишаються окремими встановленнями).
• 3.2.0 (2025-09-14) — Коміт випуску в beancount/beancount; помітна робота, орієнтована на користувача, у цьому вікні включає багатофайловий bean-format, уточнення допусків/точності та обслуговування wheel/CI (див. посилання на порівняння вище).
• 3.2.1–3.2.3 (2026) — Подальші бінарні та пакувальні випуски (включно з тестовим покриттям Python 3.14 і каркасом документації, згаданими в підсумку 3.2.1 у списку розсилки). Встановлюйте за допомогою pip install -U beancount і при оновленні прив'язуйте супутні пакети (beanquery, beangulp) до відповідних основних версій.

Fava: Fava 1.30 додала підтримку Beancount 3 (2024-12-29). Fava 1.30.13 (2026-05-19) прибрала підтримку Beancount 2 і очікує beangulp для імпортерів. Поточна лінійка PyPI станом на 2026-09-15 — 1.30.16. Поєднуйте оновлення Fava з бухгалтерською книгою Beancount 3.

Міграція з v2 на v3​

Для більшості користувачів міграція з Beancount v2 на v3 є відносно простою:

1. Файли бухгалтерських книг: жодних змін у ваших файлах .beancount не потрібно.
2. Встановлення: вам потрібно буде встановити нові окремі пакети, такі як beanquery та beangulp, за допомогою pip.
3. Скрипти імпортерів: якщо у вас є власні імпортери, вам потрібно буде оновити їх для використання нового API beangulp. Це в основному передбачає зміну базового класу, від якого успадковуються ваші імпортери, та коригування деяких сигнатур методів.
4. Fava: популярний веб-інтерфейс для Beancount, Fava, було оновлено для сумісності з v3. Переконайтеся, що у вас встановлена остання версія Fava для безперебійної роботи.

По суті, Beancount v3 — це фундаментальний випуск, який оптимізує архітектуру проєкту, роблячи його більш модульним і легшим для підтримки та розширення в довгостроковій перспективі. Хоча він вимагає певних коригувань у робочих процесах користувачів, особливо навколо імпорту даних, він закладає основу для майбутнього розвитку цього потужного інструменту обліку.

Подальше читання​

• Початок роботи з Beancount
• Довідник із синтаксису Beancount
• Довідник CLI Beancount (bea)
• Спільнотні налаштування, плагіни та робочі процеси