Configure livros Beancount com diretivas de opções

O comportamento do Beancount é personalizado com diretivas option colocadas no topo do seu arquivo principal de livro-razão. Esses pares de chave-valor controlam os nomes das suas contas raiz, quanto de desequilíbrio uma transação pode carregar e quais extensões são executadas. ⚙️

Toda opção nesta página foi carregada com o Beancount 3.2.3, e toda mensagem de erro citada é a que essa versão imprime. O Beancount rejeita uma opção que não reconhece — option "default_tolerance" "USD:0.01" falha com Invalid option: 'default_tolerance' — portanto, uma opção copiada de um guia mais antigo não falha silenciosamente. Execute bea check no seu arquivo após alterar qualquer coisa aqui.

Opções de Configuração Principais​

Estas opções controlam a configuração fundamental do seu livro-razão.

Configurações Básicas​

Estas são algumas das opções mais comuns que você definirá.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"

• title: Define o título para relatórios e interfaces web. O padrão é Beancount.
• render_commas: Se verdadeiro, os números nos relatórios são formatados com separadores de milhares (ex.: 1,000,000.00). O padrão é falso. Qualquer um de 1, TRUE, true ou yes é lido como verdadeiro; qualquer outra string é lida como falso.
• plugin_processing_mode: Ou default (o padrão) ou raw. Qualquer outro valor falha com Error for option 'plugin_processing_mode'.

raw não é uma versão mais suave de default — é o interruptor que desativa os estágios de processamento do próprio Beancount. Sob default, o Beancount executa beancount.ops.documents antes dos seus plugins e beancount.ops.pad e beancount.ops.balance depois deles. Sob raw, ele executa apenas os plugins que você lista, portanto diretivas pad nunca são aplicadas e as verificações de balance nunca são feitas:

; 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

Altere essa linha para default e o mesmo arquivo relata Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Use raw apenas quando você estiver deliberadamente reimplementando esses estágios você mesmo.

Personalização de Nomes de Contas​

Você pode renomear os cinco tipos fundamentais de contas do Beancount. Isso não é cosmético. A opção redefine quais nomes de raiz o analisador aceita, então toda conta no seu arquivo deve usar o novo nome, e o antigo se torna inválido.

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

Deixe um único lançamento na raiz antiga e o arquivo para de carregar com Invalid account name: Assets:Banque:Courant. As cinco opções são name_assets, name_liabilities, name_equity, name_income e name_expenses; cada valor deve ser uma única palavra capitalizada sem dois-pontos, ou você recebe Error for option 'name_assets': Invalid root account name. Renomeie as raízes ao iniciar um livro-razão, não no meio dele.

Configuração de Contas de Patrimônio Líquido​

O Beancount sintetiza várias contas de patrimônio líquido quando resume um período — saldos de abertura, lucros retidos e conversões de moeda. Estas opções as nomeiam.

Cada valor é um nome de folha, e o Beancount o une sob name_equity para você. Escrever a raiz de patrimônio líquido você mesmo produz Equity:Equity:Opening-Balances, que é uma conta diferente da que você pretendia.

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_rounding é a exceção neste grupo: ela aceita um nome de conta completo e é armazenada exatamente como escrita, por isso Equity:Rounding acima está correto e não é um prefixo duplicado. Ela também não é definida por padrão, e no Beancount 3.2.3 defini-la não tem efeito no carregamento — veja Precisão e Tolerâncias para o que realmente acontece com um resíduo.

Configurações de Precisão e Tolerância​

Estas opções controlam quanto desequilíbrio o Beancount aceita em uma transação.

Configuração de Tolerância Padrão​

O Beancount infere uma tolerância para cada transação a partir do número de casas decimais em seus lançamentos. Estas três opções ajustam essa inferência.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"

• inferred_tolerance_default: Um piso por moeda, usado quando uma transação não tem decimais para inferir. A sintaxe é <currency>:<number>, e * define todas as moedas de uma vez. Repita a opção para definir várias.
• tolerance_multiplier: A fração do menor dígito que conta como tolerável, padrão 0.5. Não é um aumento percentual: 1.2 torna cada tolerância inferida 2,4 vezes o padrão.
• infer_tolerance_from_cost: Se verdadeiro, lançamentos mantidos a custo ampliam a tolerância também na moeda de custo. Desativado por padrão.

O nome antigo inferred_tolerance_multiplier ainda define o mesmo valor, mas relata Renamed to 'tolerance_multiplier'. como um erro de carregamento, então bea check falha em um arquivo que o usa. Renomeie-o.

Método de Registro​

Esta opção define a regra padrão para escolher qual lote uma redução consome. Dê a uma conta uma regra diferente em sua diretiva open.

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

O Beancount 3.2.3 aceita exatamente sete nomes: STRICT (o padrão), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO e AVERAGE. Qualquer outra coisa é rejeitada no carregamento com Error for option 'booking_method' — incluindo SIMPLE e FULL, que não são métodos de registro e nunca foram. AVERAGE é aceito aqui, mas não tem implementação por trás; uma redução sob ele gera AVERAGE method is not supported. Gerenciamento de Inventários funciona através de todos os sete no mesmo livro-razão.

Gerenciamento de Moedas​

A configuração adequada de moedas é vital para relatórios precisos.

Moeda Operacional​

Uma moeda operacional é uma moeda na qual você deseja que os relatórios totalizem. Repita a opção para declarar mais de uma; os valores se acumulam em vez de se substituírem.

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

Declarar moedas operacionais informa às ferramentas de relatório para dar a cada uma sua própria coluna. conversion_currency nomeia a moeda imaginária na qual o Beancount registra conversões a uma taxa de zero; ela já tem como padrão NOTHING, e a única razão para defini-la é escolher um espaço reservado diferente que seu livro-razão definitivamente nunca usa como uma mercadoria real.

Gerenciamento de Documentos​

O Beancount pode vincular transações a arquivos externos, como recibos ou faturas. A opção documents dá a ele uma pasta para escanear.

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

O caminho naquele bloco é uma ilustração — substitua pelo seu antes de executar. As regras são estritas, e cada uma delas é uma não-operação silenciosa em vez de um erro quando você as viola:

• A pasta deve existir. Uma ausente falha o carregamento com Document root '/no/such/place' does not exist.
• Subpastas são nomes de contas. Uma declaração para Assets:US:BofA:Checking pertence a <root>/Assets/US/BofA/Checking/. Um arquivo solto na raiz é ignorado.
• A conta deve estar aberta. Documentos encontrados sob uma conta que seu livro-razão nunca abre são ignorados sem aviso.
• Nomes de arquivos começam com uma data, no formato YYYY-MM-DD.description.ext (ex.: 2025-07-28.amazon-order.pdf). Qualquer outra coisa na pasta é ignorada.
• Os caminhos podem ser absolutos ou relativos ao arquivo principal do livro-razão, e a opção pode ser repetida para várias pastas.

Sistema de Plugins​

A funcionalidade do Beancount pode ser estendida com plugins.

Configuração de Plugins​

Um plugin é carregado com uma diretiva plugin autônoma, não com option. option "plugin" "..." falha com 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

Esse arquivo carrega porque auto_accounts abre ambas as contas para você; exclua a linha plugin e ele relata Invalid reference to unknown account 'Expenses:Food:Coffee'. Um plugin que recebe configuração a recebe como uma segunda string, plugin "module" "config". Os plugins são executados na ordem em que você os escreve, após o estágio documents do próprio Beancount e antes de seus estágios pad e balance — a menos que você defina plugin_processing_mode como raw, o que remove esses estágios inteiramente.

Limites Técnicos e Restrições​

Estas opções controlam aspectos técnicos do analisador do Beancount.

Manipulação de Strings​

Você pode definir um limite no número de linhas permitidas em uma string multilinha, para que uma aspa não terminada seja relatada perto de onde você a digitou, em vez de no final do arquivo.

option "long_string_maxlines" "64"

Precisão de Interpolação​

Por padrão, o Beancount usa uma tolerância para dois trabalhos diferentes: preencher um valor ausente e decidir se a transação equilibra. Ativar isso usa a tolerância inferida mais fina para o primeiro e a mais folgada para o segundo, o que impede que valores interpolados se desviem.

option "use_precise_interpolation" "TRUE"

Não há opção para tolerâncias explícitas em um lançamento. A única sintaxe de tolerância explícita que o Beancount 3.2.3 tem é o til em uma diretiva balance — 4.271 ~ 0.01 RGAGX — e ela não precisa de opção alguma. Um til dentro de um lançamento de transação é um erro de sintaxe.

Opções Obsoletas e Removidas​

Três opções que guias mais antigos ainda recomendam não existem no Beancount 3.2.3. Cada linha neste bloco falha no carregamento:

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"

• experiment_explicit_tolerances — a sintaxe ~ no nível de lançamento que ela habilitava se foi; use o til de uma diretiva balance em vez disso.
• use_legacy_fixed_tolerances — as tolerâncias fixas 0.005/0.015 se foram; a tolerância é inferida por transação, ajustada com tolerance_multiplier e inferred_tolerance_default.
• default_tolerance — substituída por inferred_tolerance_default para balanceamento e display_precision para renderização.

Três outras ainda funcionam, mas relatam um erro de depreciação, o que é suficiente para falhar no bea check:

• inferred_tolerance_multiplier — renomeada para tolerance_multiplier.
• allow_pipe_separator — aceita o antigo | entre beneficiário e narração.
• allow_deprecated_none_for_tags_and_links — aceita um None literal onde tags e links pertencem.

As opções do Fava são separadas​

Tudo nesta página é lido pelo próprio Beancount. As configurações do próprio Fava não são diretivas option — são diretivas custom "fava-option" com uma data, e o Beancount as ignora. Escrever uma configuração do Fava como uma option falha com Invalid option. Veja Opções do Fava para essa lista.

Configuração Recomendada ✅​

Para a maioria dos usuários, a seguinte configuração fornece um ponto de partida robusto e sensato. É um arquivo, e ele carrega.

; 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"

Comentários começam com ;. Um comentário // é um erro de sintaxe no Beancount, e ele leva o resto do arquivo junto.

Esta configuração fornece uma base sólida para um novo livro-razão Beancount, garantindo relatórios claros, controle sensato de precisão e uma estrutura lógica de contas de patrimônio líquido.