Configuración de Opciones

El comportamiento de Beancount se personaliza con directivas option colocadas en la parte superior de su archivo principal de libro mayor. Estos pares clave-valor controlan los nombres de sus cuentas raíz, cuánto desequilibrio puede tener una transacción, y qué extensiones se ejecutan. ⚙️

Cada opción en esta página se probó con Beancount 3.2.3, y cada mensaje de error citado es el que esa versión imprime. Beancount rechaza una opción que no reconoce — option "default_tolerance" "USD:0.01" falla con Invalid option: 'default_tolerance' — por lo que una opción copiada de una guía más antigua no falla silenciosamente. Ejecute bea check en su archivo después de cambiar cualquier cosa aquí.

Opciones Principales de Configuración​

Estas opciones controlan la configuración fundamental de su libro mayor.

Configuración Básica​

Estas son algunas de las opciones más comunes que establecerá.

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

• title: Establece el título para informes e interfaces web. El valor predeterminado es Beancount.
• render_commas: Si es verdadero, los números en los informes se formatean con separadores de miles (por ejemplo, 1,000,000.00). El valor predeterminado es falso. Cualquiera de 1, TRUE, true o yes se lee como verdadero; cualquier otra cadena se lee como falso.
• plugin_processing_mode: Puede ser default (el valor predeterminado) o raw. Cualquier otro valor falla con Error for option 'plugin_processing_mode'.

raw no es una versión más suave de default — es el interruptor que apaga las etapas de procesamiento propias de Beancount. Bajo default, Beancount ejecuta beancount.ops.documents antes de sus plugins y beancount.ops.pad y beancount.ops.balance después de ellos. Bajo raw, solo ejecuta los plugins que usted mismo enumera, por lo que las directivas pad nunca se aplican y las verificaciones de balance nunca se realizan:

; 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

Cambie esa línea a default y el mismo archivo informa Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Use raw solo cuando esté reimplementando deliberadamente esas etapas usted mismo.

Personalización de Nombres de Cuentas​

Puede renombrar los cinco tipos de cuentas fundamentales de Beancount. Esto no es cosmético. La opción redefine qué nombres raíz acepta el analizador, por lo que cada cuenta en su archivo debe usar el nuevo nombre, y el antiguo se vuelve 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

Deje un solo asiento en la raíz antigua y el archivo deja de cargarse con Invalid account name: Assets:Banque:Courant. Las cinco opciones son name_assets, name_liabilities, name_equity, name_income y name_expenses; cada valor debe ser una palabra única en mayúsculas, sin dos puntos, o recibe Error for option 'name_assets': Invalid root account name. Renombre las raíces cuando comience un libro mayor, no a mitad de camino.

Configuración de Cuentas de Patrimonio​

Beancount sintetiza varias cuentas de patrimonio cuando resume un período — saldos iniciales, ganancias retenidas y conversiones de moneda. Estas opciones les dan nombre.

Cada valor es un nombre de hoja, y Beancount lo une bajo name_equity por usted. Escribir la raíz de patrimonio usted mismo produce Equity:Equity:Opening-Balances, que es una cuenta diferente de la que pretendía.

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 es la excepción en este grupo: toma un nombre de cuenta completo y se almacena exactamente como está escrito, por lo que Equity:Rounding arriba es correcto y no un prefijo duplicado. También está sin establecer por defecto, y en Beancount 3.2.3 establecerlo no tiene efecto al cargar — vea Precisión y Tolerancias para lo que realmente sucede con un residual.

Opciones de Precisión y Tolerancia​

Estas opciones controlan cuánto desequilibrio acepta Beancount en una transacción.

Configuración de Tolerancia Predeterminada​

Beancount infiere una tolerancia para cada transacción a partir del número de decimales en sus asientos. Estas tres opciones ajustan esa inferencia.

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

• inferred_tolerance_default: Un piso por moneda, utilizado cuando una transacción no tiene decimales de los cuales inferir. La sintaxis es <currency>:<number>, y * establece cada moneda a la vez. Repita la opción para establecer varias.
• tolerance_multiplier: La fracción del dígito más pequeño que cuenta como tolerable, predeterminado 0.5. No es un aumento porcentual: 1.2 hace cada tolerancia inferida 2.4 veces la predeterminada.
• infer_tolerance_from_cost: Si es verdadero, los asientos mantenidos a costo amplían la tolerancia también en la moneda del costo. Desactivado por defecto.

El nombre antiguo inferred_tolerance_multiplier todavía establece el mismo valor, pero reporta Renamed to 'tolerance_multiplier'. como un error de carga, por lo que bea check falla en un archivo que lo usa. Renómbrelo.

Método de Reserva​

Esta opción establece la regla predeterminada para elegir qué lote se reduce. Dé a una cuenta una regla diferente en su directiva open.

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

Beancount 3.2.3 acepta exactamente siete nombres: STRICT (el predeterminado), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO y AVERAGE. Cualquier otra cosa se rechaza al cargar con Error for option 'booking_method' — incluyendo SIMPLE y FULL, que no son métodos de reserva y nunca lo fueron. AVERAGE se acepta aquí pero no tiene implementación detrás; una reducción bajo él eleva AVERAGE method is not supported. Gestión de Inventario funciona a través de los siete en el mismo libro mayor.

Gestión de Monedas​

Una configuración de moneda adecuada es vital para informes precisos.

Moneda Operativa​

Una moneda operativa es una moneda en la que desea que los informes totalicen. Repita la opción para declarar más de una; los valores se acumulan en lugar de reemplazarse entre sí.

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

Declarar monedas operativas les dice a las herramientas de informes que den a cada una su propia columna. conversion_currency nombra la moneda imaginaria en la que Beancount registra conversiones a una tasa de cero; ya tiene un valor predeterminado de NOTHING, y la única razón para establecerlo es elegir un marcador de posición diferente que su libro mayor definitivamente nunca use como mercancía real.

Gestión de Documentos​

Beancount puede vincular transacciones a archivos externos como recibos o facturas. La opción documents le da una carpeta para escanear.

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

La ruta en ese bloque es una ilustración — sustituya la suya propia antes de ejecutarla. Las reglas son estrictas, y cada una de ellas es una no-operación silenciosa en lugar de un error cuando la hace mal:

• La carpeta debe existir. Una que falta falla la carga con Document root '/no/such/place' does not exist.
• Las subcarpetas son nombres de cuentas. Un estado de cuenta para Assets:US:BofA:Checking pertenece en <root>/Assets/US/BofA/Checking/. Un archivo suelto en la raíz se ignora.
• La cuenta debe estar abierta. Los documentos encontrados bajo una cuenta que su libro mayor nunca abre se omiten sin advertencia.
• Los nombres de archivo comienzan con una fecha, en la forma YYYY-MM-DD.description.ext (por ejemplo, 2025-07-28.amazon-order.pdf). Cualquier otra cosa en la carpeta se ignora.
• Las rutas pueden ser absolutas o relativas al archivo principal del libro mayor, y la opción puede repetirse para varias carpetas.

Sistema de Plugins​

La funcionalidad de Beancount se puede extender con plugins.

Configuración de Plugins​

Un plugin se carga con una directiva plugin independiente, no con option. option "plugin" "..." falla con 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

Ese archivo carga porque auto_accounts abre ambas cuentas por usted; elimine la línea plugin y reporta Invalid reference to unknown account 'Expenses:Food:Coffee'. Un plugin que toma configuración la recibe como una segunda cadena, plugin "module" "config". Los plugins se ejecutan en el orden en que los escribe, después de la etapa documents propia de Beancount y antes de sus etapas pad y balance — a menos que establezca plugin_processing_mode a raw, lo que elimina esas etapas por completo.

Límites y Restricciones Técnicos​

Estas opciones controlan aspectos técnicos del analizador de Beancount.

Manejo de Cadenas​

Puede establecer un límite en el número de líneas permitidas en una cadena multilínea, para que una comilla sin terminar se reporte cerca de donde la escribió en lugar de al final del archivo.

option "long_string_maxlines" "64"

Precisión de Interpolación​

Por defecto, Beancount usa una tolerancia para dos trabajos diferentes: completar un monto faltante y decidir si la transacción cuadra. Activar esto usa la tolerancia inferida más fina para el primero y la más amplia para el segundo, lo que evita que los montos interpolados se desvíen.

option "use_precise_interpolation" "TRUE"

No hay opción para tolerancias explícitas en un asiento. La única sintaxis de tolerancia explícita que Beancount 3.2.3 tiene es la tilde en una directiva balance — 4.271 ~ 0.01 RGAGX — y no necesita ninguna opción en absoluto. Una tilde dentro de un asiento de transacción es un error de sintaxis.

Opciones Obsoletas y Eliminadas​

Tres opciones que las guías más antiguas aún recomiendan no existen en Beancount 3.2.3. Cada línea en este bloque falla la carga:

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

• experiment_explicit_tolerances — la sintaxis ~ a nivel de asiento que habilitaba se ha ido; use la tilde de una directiva balance en su lugar.
• use_legacy_fixed_tolerances — las tolerancias fijas 0.005/0.015 se han ido; la tolerancia se infiere por transacción, ajustada con tolerance_multiplier e inferred_tolerance_default.
• default_tolerance — reemplazada por inferred_tolerance_default para el equilibrio y display_precision para el renderizado.

Tres más todavía funcionan pero reportan un error de obsolecencia, que es suficiente para fallar bea check:

• inferred_tolerance_multiplier — renombrada a tolerance_multiplier.
• allow_pipe_separator — acepta el antiguo | entre beneficiario y narración.
• allow_deprecated_none_for_tags_and_links — acepta un None literal donde pertenecen etiquetas y enlaces.

Las opciones de Fava son separadas​

Todo en esta página es leído por Beancount mismo. Los ajustes propios de Fava no son directivas option en absoluto — son directivas custom "fava-option" con una fecha, y Beancount las ignora. Escribir un ajuste de Fava como una option falla con Invalid option. Vea Opciones de Fava para esa lista.

Configuración Recomendada ✅​

Para la mayoría de los usuarios, la siguiente configuración proporciona un punto de partida robusto y sensato. Es un archivo, y carga.

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

Los comentarios comienzan con ;. Un comentario // es un error de sintaxis en Beancount, y se lleva el resto del archivo con él.

Esta configuración proporciona una base sólida para un nuevo libro mayor de Beancount, asegurando informes claros, control de precisión sensato y una estructura de cuentas de patrimonio lógica.