Actualizado al 2026-09-15.
El poder de Beancount no reside solo en su formato de texto plano, sino en su extensibilidad mediante plugins. Los plugins nativos son módulos integrados que mejoran la funcionalidad de Beancount, automatizan tareas tediosas y hacen cumplir las mejores prácticas contables. En esta guía completa, exploraremos todos los plugins nativos disponibles en Beancount y cómo usarlos de manera efectiva.
Para la sintaxis de directivas sobre la que operan estos plugins, consulta la referencia de sintaxis de Beancount. Para flujos de trabajo reales de la comunidad que combinan plugins con importadores y Fava, consulta la vitrina de la comunidad. Las opciones del libro mayor que interactúan con plugins se encuentran en Configuración de opciones.
¿Qué son los plugins de Beancount?
Los plugins de Beancount son módulos de Python que procesan las entradas de tu libro mayor para agregar capacidades de automatización, validación o transformación. Se ejecutan durante la fase de carga de tu archivo de libro mayor y pueden:
- Automatizar tareas repetitivas (por ejemplo, crear declaraciones de cuentas)
- Validar la integridad de los datos (por ejemplo, verificar transacciones duplicadas)
- Transformar entradas (por ejemplo, generar entradas de precios a partir de transacciones)
- Hacer cumplir reglas contables (por ejemplo, un solo commodity por cuenta)
Cómo usar los plugins
Para habilitar un plugin en tu archivo de Beancount, agrega una directiva plugin en la parte superior de tu libro mayor:
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"Algunos plugins aceptan opciones de configuración:
; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"Categorías de plugins nativos
Los plugins nativos de Beancount se dividen en cuatro categorías principales:
1. Plugins de automatización
2. Plugins de validación
3. Plugins de transformación
4. Meta-plugins
1. Plugins de automatización
Estos plugins automatizan tareas repetitivas de teneduría de libros, ahorrándote tiempo y reduciendo errores manuales.
auto_accounts - Declaraciones automáticas de cuentas
Qué hace: Inserta automáticamente directivas Open para cuentas que aparecen en transacciones pero que no han sido declaradas explícitamente.
Por qué usarlo: Elimina la necesidad de declarar manualmente cada cuenta antes de usarla. Perfecto para empezar rápidamente o para usuarios que prefieren un código mínimo.
Ejemplo:
plugin "beancount.plugins.auto_accounts"
2026-01-01 * "Coffee shop"
Expenses:Food:Coffee 4.50 USD
Assets:Cash -4.50 USDSin el plugin, necesitarías agregar manualmente:
2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:CashCuándo usarlo: Ideal para principiantes o para quienes desean un libro mayor menos verboso. Sin embargo, las declaraciones explícitas de cuentas pueden ayudar a detectar errores tipográficos.
close_tree - Cierre automático de jerarquía de cuentas
Qué hace: Cuando cierras una cuenta principal, este plugin cierra automáticamente todas sus cuentas descendientes.
Por qué usarlo: Mantiene la consistencia en tu jerarquía de cuentas. Si cierras Assets:Investments, todas las subcuentas como Assets:Investments:Stocks y Assets:Investments:Bonds se cerrarán automáticamente.
Ejemplo:
plugin "beancount.plugins.close_tree"
2025-06-30 close Assets:Investments
; These will be automatically closed:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstateCuándo usarlo: Al reestructurar tu jerarquía de cuentas o cerrar categorías completas de cuentas.
implicit_prices - Generación automática de entradas de precios
Qué hace: Sintetiza directivas Price a partir de asientos de transacciones que incluyen costos (@) o precios (@@).
Por qué usarlo: Puebla tu base de datos de precios automáticamente desde tus transacciones, lo que permite informes precisos de valor de mercado sin entradas manuales de precios.
Ejemplo:
plugin "beancount.plugins.implicit_prices"
2026-01-02 * "Buy AAPL shares"
Assets:Investments:Stocks 10 AAPL @ 150.00 USD
Assets:Cash -1500.00 USDEsto genera automáticamente:
2026-01-02 price AAPL 150.00 USDCuándo usarlo: Esencial para el seguimiento de inversiones y la contabilidad multidivisa donde deseas un historial automático de precios.
2. Plugins de validación
Estos plugins hacen cumplir la integridad de los datos y las mejores prácticas contables, detectando errores antes de que se conviertan en problemas.
noduplicates - Detección de transacciones duplicadas
Qué hace: Verifica que no haya dos transacciones idénticas calculando y comparando hashes de los datos de las transacciones.
Por qué usarlo: Previene entradas duplicadas accidentales, especialmente al importar transacciones de múltiples fuentes.
Ejemplo:
; @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 USDCuándo usarlo: Siempre recomendado, especialmente si estás importando desde extractos bancarios o usando múltiples fuentes de datos.
check_commodity - Validación de declaración de commodities
Qué hace: Asegura que todos los commodities utilizados en tu libro mayor tengan directivas Commodity correspondientes.
Por qué usarlo: Hace cumplir declaraciones explícitas de commodities, ayudándote a mantener una lista limpia de activos y divisas.
Ejemplo:
; @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 USDCuándo usarlo: Recomendado para mantener un seguimiento estricto de commodities y prevenir errores tipográficos en los símbolos de cotización.
check_average_cost - Validación de base de costo
Qué hace: Verifica que la base de costo se preserve correctamente en las transacciones, especialmente al usar el método de contabilización de costo promedio.
Por qué usarlo: Asegura que tu contabilidad de costos sea precisa para la declaración de impuestos y los cálculos de ganancias de capital.
Cuándo usarlo: Esencial para carteras de inversión y cualquier escenario donde el seguimiento preciso de costos sea importante.
check_closing - Validación de cierre de saldos
Qué hace: Expande los metadatos de closing en verificaciones de saldo, asegurando que las posiciones queden en cero después de operaciones de cierre.
Por qué usarlo: Confirma que cuando vendes una posición completa, el saldo sea realmente cero (sin acciones fraccionarias restantes).
Ejemplo:
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 USDLa etiqueta #closing indica al plugin que verifique que tu posición en AAPL sea cero después de esta transacción.
Cuándo usarlo: Al vender posiciones completas para asegurar que no quede nada.
coherent_cost - Verificación de consistencia de divisa/costo
Qué hace: Valida que las divisas no se usen de manera inconsistente, tanto con como sin anotaciones de costo.
Por qué usarlo: Previene mezclar divisas simples (como 100 USD) con divisas con costo (como 100 USD {1.2 CAD}), lo que puede causar errores contables.
Cuándo usarlo: Recomendado para libros mayores multidivisa para mantener la consistencia.
leafonly - Cumplimiento de cuentas hoja
Qué hace: Asegura que solo las cuentas hoja (cuentas sin hijos) reciban asientos.
Por qué usarlo: Hace cumplir una jerarquía de cuentas limpia donde las cuentas de resumen como Expenses:Food no tengan asientos directos, solo sus hijas como Expenses:Food:Groceries y Expenses:Food:Restaurants.
Ejemplo:
; @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 USDCuándo usarlo: Cuando deseas mantener una contabilidad jerárquica estricta con una categorización clara.
nounused - Detección de cuentas no utilizadas
Qué hace: Identifica cuentas que fueron abiertas pero nunca se usaron realmente en ninguna transacción.
Por qué usarlo: Te ayuda a limpiar tus declaraciones de cuentas e identificar posibles errores tipográficos o cuentas abandonadas.
Cuándo usarlo: Periódicamente, para auditar y limpiar tu estructura de cuentas.
onecommodity - Un solo commodity por cuenta
Qué hace: Hace cumplir que cada cuenta contenga solo un tipo de commodity.
Por qué usarlo: Previene mezclar diferentes activos en la misma cuenta, lo que generalmente es una buena práctica contable.
Ejemplo:
; @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 USDCuándo usarlo: Cuando prefieres una separación estricta de cuentas (una cuenta por acción/activo).
sellgains - Validación de ganancias de capital
Qué hace: Verifica de forma cruzada las ganancias de capital declaradas contra las ganancias calculadas de las ventas de lotes, asegurando que tus cálculos de pérdidas y ganancias sean precisos.
Por qué usarlo: Detecta errores en los cálculos manuales de ganancias de capital, algo esencial para una declaración de impuestos precisa.
Ejemplo:
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 correctEl plugin verificará: Producto de la venta (1500) - Base de costo (1400) = Ganancias (100)
Cuándo usarlo: Esencial para cualquier persona que opere acciones, criptomonedas u otros activos donde las ganancias de capital son relevantes.
unique_prices - Verificación de unicidad de precios
Qué hace: Asegura que solo haya una entrada de precio por commodity y por fecha.
Por qué usarlo: Previene datos de precios conflictivos que podrían llevar a valoraciones incorrectas.
Cuándo usarlo: Recomendado al ingresar precios manualmente o importar desde múltiples fuentes de precios.
check_drained - Validación de cuentas drenadas
Qué hace: Señala cuentas que aún mantienen un saldo (incluyendo divisas sin precio o lotes residuales) cuando esperabas que estuvieran vacías después de transferencias o cierres.
Por qué usarlo: Detecta saldos residuales que las aserciones de balance y las etiquetas #closing pueden pasar por alto, especialmente útil después de movimientos multidivisa.
Estado (verificado el 2026-09-15): Presente en el árbol de Beancount 3.x en beancount/plugins/check_drained.py en la línea actual de PyPI (3.2.3).
Cuándo usarlo: Después de grandes reorganizaciones de cartera o al cerrar cuentas de corretaje.
3. Plugins de transformación
Estos plugins modifican o mejoran los datos de tu libro mayor de maneras útiles.
currency_accounts - Cuentas de negociación de divisas
Qué hace: Implementa cuentas de negociación de divisas para rastrear conversiones de forex explícitamente.
Por qué usarlo: Proporciona un seguimiento detallado de las transacciones de conversión de divisas, útil para estándares contables que lo requieren.
Cuándo usarlo: Cuando necesitas rastrear ganancias/pérdidas de forex por separado o cumplir con requisitos contables específicos.
commodity_attr - Validación de atributos de commodities
Qué hace: Valida que las directivas de commodities tengan los atributos requeridos (como export, name, etc.).
Por qué usarlo: Asegura que tus metadatos de commodities sean completos y consistentes.
Cuándo usarlo: Cuando mantienes metadatos detallados de commodities para fines de informes o exportación.
4. Meta-plugins
Estos plugins son colecciones de otros plugins por conveniencia.
auto - Todos los plugins automáticos
Qué hace: Habilita una colección de plugins "laxos" o automáticos en una sola directiva.
Cuándo usarlo: Configuración rápida para usuarios que desean máxima automatización con configuración mínima.
pedantic - Todos los plugins de validación
Qué hace: Habilita todos los plugins de validación estrictos de una vez.
Por qué usarlo: Hace cumplir la máxima integridad de datos y rigor contable. Excelente para libros mayores de producción o cuando la precisión es primordial.
Ejemplo:
plugin "beancount.plugins.pedantic"
; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_pricesCuándo usarlo: Para libros mayores de producción donde deseas la máxima validación y estás dispuesto a mantener prácticas contables más estrictas.
Configuraciones recomendadas de plugins
Para principiantes
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"Este conjunto mínimo proporciona automatización mientras previene errores comunes.
Para inversores
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"Se enfoca en el seguimiento de inversiones y la precisión de las ganancias de capital.
Para contabilidad estricta
plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"Máxima validación para entornos de producción.
Configuración predeterminada en Beancount.io
En Beancount.io, incluimos el plugin auto_accounts por defecto en todos los archivos de libro mayor nuevos:
plugin "beancount.plugins.auto_accounts"Esto proporciona un gran equilibrio entre facilidad de uso y funcionalidad para empezar rápidamente.
Estado de los plugins verificado el 2026-09-15
Contra el árbol vivo beancount/plugins en Beancount 3.2.3 (PyPI, 2026-09-15):
| Módulo del plugin | Aún presente | Notas |
|---|---|---|
auto_accounts, close_tree, implicit_prices | Sí | Conjunto de automatización sin cambios |
noduplicates, check_commodity, check_average_cost, check_closing, coherent_cost, leafonly, nounused, onecommodity, sellgains, unique_prices | Sí | Conjunto de validación sin cambios |
currency_accounts, commodity_attr | Sí | Conjunto de transformación sin cambios |
auto, pedantic | Sí | Meta-plugins sin cambios |
check_drained | Sí | Documentado arriba; era fácil pasarlo por alto en guías antiguas |
Nada de ese conjunto nativo fue eliminado entre el borrador original de esta guía y la fecha indicada. Los plugins de la comunidad (no nativos) todavía pertenecen a la lista de plugins de Awesome Beancount y a la vitrina de la comunidad: trata los repositorios de terceros como versionados de forma independiente y verifica la última versión de cada repositorio antes de habilitarlos en un libro mayor de producción.
Mejores prácticas
-
Empieza con lo mínimo, agrega según necesites: Comienza con
auto_accountsynoduplicates, luego agrega plugins de validación a medida que tu libro mayor madure. -
Prueba los plugins individualmente: Al agregar varios plugins, habilítalos uno a la vez para entender sus efectos.
-
Lee los mensajes de error con atención: Los errores de plugins a menudo señalan problemas contables reales que deben corregirse.
-
Usa
pedanticpara producción: Una vez que tu flujo de trabajo esté establecido, considera habilitar la validación estricta. -
Combina con plugins personalizados: Los plugins nativos funcionan junto con plugins personalizados como el plugin de pronóstico para una funcionalidad máxima.
Más allá de los plugins nativos
Si bien los plugins nativos proporcionan funcionalidad central, el ecosistema de Beancount incluye muchos plugins desarrollados por la comunidad para necesidades especializadas:
- fava.plugins.forecast - Para pronosticar transacciones recurrentes
- fava.plugins.link_documents - Para vincular transacciones a archivos de recibos
- Importadores personalizados para formatos CSV específicos de bancos
- Calculadoras e informes específicos de impuestos
Explora el ecosistema de Beancount para más opciones, y la vitrina de la comunidad para ver cómo las personas combinan plugins nativos con importadores y Fava.
Conclusión
Los plugins nativos de Beancount transforman la contabilidad en texto plano de un proceso manual a un sistema de gestión financiera automatizado, validado y robusto. Al comprender y aprovechar estas herramientas integradas, puedes:
- ✅ Automatizar tareas tediosas de teneduría de libros
- ✅ Detectar errores antes de que se conviertan en problemas
- ✅ Mantener una integridad de datos estricta
- ✅ Generar informes financieros precisos
- ✅ Enfocarte en la información financiera en lugar de la entrada de datos
Comienza a experimentar con estos plugins en tu libro mayor hoy. Empieza con auto_accounts e implicit_prices, luego agrega gradualmente plugins de validación a medida que tus prácticas contables maduren.
¿Listo para probar estos plugins? Dirígete a Beancount.io y comienza a usarlos en tu archivo de libro mayor hoy mismo.
Fuentes
- Referencia de API de Plugins de Beancount
- Guía de Scripting y Plugins de Beancount
- Plugins y opciones de Beancount por Bryan Alves
- Repositorio de GitHub de Beancount
¿Tienes preguntas sobre los plugins de Beancount? Únete a la discusión en nuestro foro comunitario o consulta nuestra documentación.
Explora un libro mayor de ejemplo de criptomonedas en vivo:
