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

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

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

Синтаксис директив, с которыми работают эти плагины, описан в [справочнике по синтаксису Beancount](/docs/Basics/syntax). Реальные примеры рабочих процессов сообщества, сочетающих плагины с импортерами и Fava, смотрите в [витрине сообщества](/docs/community-showcase). Параметры журнала, взаимодействующие с плагинами, описаны в [конфигурации параметров](/docs/Basics/options-configuration).



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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

**Пример:**

```beancount
plugin "beancount.plugins.auto_accounts"

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

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

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

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

---

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

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

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

**Пример:**

```beancount
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` из проводок транзакций, которые включают стоимость (`@`) или цены (`@@`).

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

**Пример:**

```beancount
plugin "beancount.plugins.implicit_prices"

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

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

```beancount
2026-01-02 price AAPL  150.00 USD
```

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

---

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

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

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

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

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

**Пример:**

```beancount
; @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`.

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

**Пример:**

```beancount
; @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` в проверки баланса, гарантируя нулевые позиции после закрытия сделок.

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

**Пример:**

```beancount
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`.

**Пример:**

```beancount
; @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` — Один товар на счет

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

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

**Пример:**

```beancount
; @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` — Проверка прироста капитала

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

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

**Пример:**

```beancount
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`](https://github.com/beancount/beancount/blob/master/beancount/plugins/check_drained.py) на текущей линии PyPI (**3.2.3**).

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

---

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

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

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

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

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

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

---

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

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

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

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

---

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

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

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

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

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

---

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

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

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

**Пример:**

```beancount
plugin "beancount.plugins.pedantic"

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

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

---

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

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

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

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

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

```beancount
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"
```

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

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

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

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

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

На [Beancount.io](https://beancount.io) мы включаем плагин `auto_accounts` по умолчанию во все новые файлы журналов:

```beancount
plugin "beancount.plugins.auto_accounts"
```

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

---

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

Сравнение с текущим деревом [`beancount/plugins`](https://github.com/beancount/beancount/tree/master/beancount/plugins) на Beancount **3.2.3** (PyPI, 2026-09-15):

| Модуль плагина | Все еще присутствует | Примечания |
| --- | --- | --- |
| `auto_accounts`, `close_tree`, `implicit_prices` | Да | Набор автоматизации без изменений |
| `noduplicates`, `check_commodity`, `check_average_cost`, `check_closing`, `coherent_cost`, `leafonly`, `nounused`, `onecommodity`, `sellgains`, `unique_prices` | Да | Набор проверки без изменений |
| `currency_accounts`, `commodity_attr` | Да | Набор преобразования без изменений |
| `auto`, `pedantic` | Да | Мета-плагины без изменений |
| `check_drained` | Да | Описан выше; его было легко пропустить в старых руководствах |

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

---

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

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

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

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

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

5. **Комбинируйте с пользовательскими плагинами:** Встроенные плагины работают вместе с пользовательскими плагинами, такими как [плагин forecast](https://beancount.io/blog/2022/05/30/forecast-plugin), для максимальной функциональности.

---

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

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

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

Изучите [экосистему Beancount](https://beancount.io/awesome-beancount) для получения дополнительных вариантов и [витрину сообщества](/docs/community-showcase) для примеров того, как люди сочетают встроенные плагины с импортерами и Fava.

---

## Заключение

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

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

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

---

## Источники

- [Справочник по API плагинов Beancount](https://beancount.github.io/docs/api_reference/beancount.plugins.html)
- [Руководство по скриптам и плагинам Beancount](https://beancount.github.io/docs/beancount_scripting_plugins.html)
- [Плагины и параметры Beancount от Брайана Алвеса](https://bryanalves.github.io/posts/2022-09-01-beancount-plugins-and-options/)
- [Репозиторий Beancount на GitHub](https://github.com/beancount/beancount)

---

_Есть вопросы о плагинах Beancount? Присоединяйтесь к обсуждению на нашем [форуме сообщества](https://beancount.io/forum) или ознакомьтесь с нашей [документацией](https://beancount.io/docs/help-center)._

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

<LedgerEmbed
  username="open_ledger"
  ledger="crypto-example"
  page=""
  title="Пример журнала криптовалют"
/>
