Configuración de Opciones

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

Cada opción en esta página se cargó 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 antigua no falla silenciosamente. Ejecuta bea check en tu archivo después de cambiar cualquier cosa aquí.

Opciones de Configuración Básicas​

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

Configuración Básica​

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

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. Valor predeterminado: Beancount.
• render_commas: Si es verdadero, los números en informes se formatean con separadores de miles (por ejemplo, 1,000,000.00). Valor predeterminado: 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 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 tus plugins y beancount.ops.pad y beancount.ops.balance después de ellos. Bajo raw, solo ejecuta los plugins que tú listes, por lo que las directivas pad nunca se aplican y las verificaciones balance nunca se comprueban:

; 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

Cambia esa línea a default y el mismo archivo reporta Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Usa raw solo cuando estés reimplementando deliberadamente esas etapas tú mismo.

Personalización de Nombres de Cuentas​

Puedes 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 tu 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

Deja una sola publicación 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 sola palabra capitalizada sin dos puntos, o recibirás Error for option 'name_assets': Invalid root account name. Renombra las raíces cuando comiences 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 divisas. Estas opciones las nombran.

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

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 se escribe, por lo que Equity:Rounding arriba es correcto y no un prefijo duplicado. También está desactivado por defecto, y en Beancount 3.2.3 configurarlo no tiene efecto en la carga — consulta Precisión y Tolerancias para ver qué sucede realmente con un residuo.

Configuración de Precisión y Tolerancias​

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 publicaciones. 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 mínimo por divisa, usado cuando una transacción no tiene decimales de los que inferir. La sintaxis es <currency>:<number>, y * establece todas las divisas a la vez. Repite la opción para configurar varias.
• tolerance_multiplier: La fracción del dígito más pequeño que cuenta como tolerable, valor predeterminado 0.5. No es un aumento porcentual: 1.2 hace que cada tolerancia inferida sea 2.4 veces la predeterminada.
• infer_tolerance_from_cost: Si es verdadero, las publicaciones mantenidas a costo amplían la tolerancia en la divisa de costo también. 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ómbralo.

Método de Contabilización​

Esta opción establece la regla predeterminada para elegir qué lote reduce una reducción. Da 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 en el momento de la carga con Error for option 'booking_method' — incluyendo SIMPLE y FULL, que no son métodos de contabilización y nunca lo fueron. AVERAGE se acepta aquí pero no tiene implementación detrás; una reducción bajo él genera AVERAGE method is not supported. Gestión de Inventarios funciona con los siete en el mismo libro mayor.

Gestión de Divisas​

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

Divisa Operativa​

Una divisa operativa es una divisa en la que quieres que los informes totalicen. Repite 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 divisas operativas indica a las herramientas de informes que den a cada una su propia columna. conversion_currency nombra la divisa imaginaria en la que Beancount contabiliza conversiones a una tasa de cero; ya tiene un valor predeterminado de NOTHING, y la única razón para configurarla es elegir un marcador de posición diferente que tu libro mayor definitivamente nunca usa 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 — sustituye la tuya antes de ejecutarlo. Las reglas son estrictas, y cada una de ellas es un no-op silencioso en lugar de un error cuando te equivocas:

• 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 a <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 tu 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 de libro mayor principal, 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 ti; elimina 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 escribes, después de la etapa documents propia de Beancount y antes de sus etapas pad y balance — a menos que establezcas plugin_processing_mode en raw, que elimina esas etapas por completo.

Límites y Restricciones Técnicas​

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

Manejo de Cadenas​

Puedes establecer un límite en el número de líneas permitidas en una cadena multilínea, para que una comilla sin cerrar se reporte cerca de donde la escribiste 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 precisa 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 una publicación. 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. Una tilde dentro de una publicación de transacción es un error de sintaxis.

Opciones Obsoletas y Eliminadas​

Tres opciones que guías 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 publicación que habilitaba ya no existe; usa la tilde de una directiva balance en su lugar.
• use_legacy_fixed_tolerances — las tolerancias fijas 0.005/0.015 ya no existen; la tolerancia se infiere por transacción, ajustada con tolerance_multiplier e inferred_tolerance_default.
• default_tolerance — reemplazada por inferred_tolerance_default para el balanceo y display_precision para la representación.

Tres más aún funcionan pero reportan un error de obsolescencia, 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. Consulta 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 lógica de cuentas de patrimonio.