Actualizado al 2026-09-15.
La versión 3 de Beancount, publicada a mediados de 2024, marca una evolución arquitectónica significativa para la popular herramienta de contabilidad en texto plano. Aunque mantiene la compatibilidad con versiones anteriores para los archivos de contabilidad de los usuarios, la estructura subyacente y las herramientas complementarias han sufrido cambios sustanciales. A continuación, un desglose de las novedades de Beancount v3 — y de lo que ha llegado en la línea 3.1–3.2 desde que se publicó esta guía.
Para la sintaxis y los primeros libros de contabilidad, consulte la referencia de sintaxis de Beancount y Primeros pasos. Para la CLI alojada que envuelve check, query, import y reports, consulte la referencia de CLI de Beancount.
Una arquitectura más modular y simplificada
El cambio más significativo en Beancount v3 es el paso a un ecosistema más modular. Varias funcionalidades clave que antes estaban incluidas en el núcleo se han separado en proyectos independientes. Esto hace que el núcleo de Beancount sea más ligero y permite un desarrollo más centrado en los componentes individuales.
Los componentes clave que ahora son paquetes separados incluyen:
- beanquery: La potente herramienta de consulta similar a SQL para sus archivos de contabilidad ahora tiene su propio paquete.
- beangulp: Este es el nuevo hogar del marco de importación de datos, que reemplaza al antiguo módulo
beancount.ingest. - beanprice: Una herramienta dedicada a obtener precios de materias primas y acciones.
Esta separación significa que los usuarios deberán instalar estos paquetes además de beancount para conservar toda la funcionalidad que tenían en la versión 2.
Cambios en las herramientas de línea de comandos y flujos de trabajo
Reflejando la nueva arquitectura modular, hay algunos cambios notables en las herramientas de línea de comandos:
bean-reportya no existe: Esta herramienta se ha eliminado. Ahora se recomienda a los usuarios usarbean-query(del paquetebeanquery) para sus necesidades de informes.- Nuevo flujo de importación: Los comandos
bean-extractybean-identifyse han eliminado del núcleo. El nuevo enfoque conbeangulpse basa en scripts. Los usuarios ahora crearán sus propios scripts de Python para manejar la importación de datos de fuentes externas como extractos bancarios.
Mejoras de sintaxis y funciones
Aunque los principios contables básicos siguen siendo los mismos, Beancount v3 introduce una flexibilidad bienvenida en su sintaxis:
- Códigos de moneda más flexibles: Las restricciones anteriores sobre la longitud y los caracteres para los nombres de moneda se han relajado. Ahora se admiten símbolos de moneda de un solo carácter.
- Banderas de transacción ampliadas: Los usuarios ahora pueden usar cualquier letra mayúscula de la A a la Z como bandera para las transacciones, lo que permite una categorización más granular.
Es importante destacar que estos cambios son compatibles con versiones anteriores, por lo que sus archivos de contabilidad existentes de Beancount v2 funcionarán sin modificaciones.
La reescritura en C++ y el rendimiento
Uno de los objetivos a largo plazo de Beancount ha sido la reescritura de sus componentes críticos para el rendimiento en C++. La versión inicial de Beancount v3 no incluía un núcleo en C++, y a fecha de 2026-09-15 sigue siendo así: la línea publicada en PyPI (hasta 3.2.3) sigue siendo la rama modular de Python v3. El trabajo histórico en C++/Bazel vive en una rama cpp separada y no forma parte de los paquetes que los usuarios instalan desde PyPI. El rendimiento diario de las versiones actuales de v3 está, por tanto, en la misma clase que el de las últimas v2, con mejoras incrementales en el parser y las herramientas, en lugar de una reescritura en C++ de un orden de magnitud.
Desde que se escribió esto (v3.1 → v3.2.x)
Fuentes primarias: el archivo CHANGES del proyecto, las vistas de comparación de GitHub para 3.1.0…3.2.0, y PyPI beancount (la última 3.2.3 a fecha de 2026-09-15).
- Línea 3.1.x — Continuación de la limpieza del empaquetado y la API tras la división modular de 3.0 (
beanquery,beangulp,beanpricesiguen siendo instalaciones separadas). - 3.2.0 (2025-09-14) — Commit de lanzamiento en
beancount/beancount; el trabajo notable orientado al usuario en este período incluyebean-formatmultiarchivo, refinamientos de tolerancia/precisión y mantenimiento de ruedas e IC (consulte el enlace de comparación anterior). - 3.2.1–3.2.3 (2026) — Lanzamientos posteriores de binarios y empaquetado (incluida la cobertura de pruebas para Python 3.14 y el andamiaje de documentación señalados en el resumen de 3.2.1 en la lista de correo). Instale con
pip install -U beancounty fije los compañeros (beanquery,beangulp) a las mismas versiones principales al actualizar.
Fava: Fava 1.30 añadió soporte para Beancount 3 (2024-12-29). Fava 1.30.13 (2026-05-19) eliminó el soporte para Beancount 2 y espera beangulp para los importadores. La línea actual en PyPI a fecha de 2026-09-15 es 1.30.16. Combine las actualizaciones de Fava con un libro de contabilidad de Beancount 3.
Migración de v2 a v3
Para la mayoría de los usuarios, la migración de Beancount v2 a v3 es relativamente sencilla:
- Archivos de contabilidad: No se necesitan cambios en sus archivos
.beancount. - Instalación: Deberá instalar los nuevos paquetes separados, como
beanqueryybeangulp, usandopip. - Scripts de importación: Si tiene importadores personalizados, deberá actualizarlos para usar la nueva API de
beangulp. Esto implica principalmente cambiar la clase base de la que heredan sus importadores y ajustar algunas firmas de métodos. - Fava: La popular interfaz web para Beancount, Fava, se ha actualizado para ser compatible con v3. Asegúrese de tener la última versión de Fava para una experiencia sin problemas.
En esencia, Beancount v3 es una versión fundacional que optimiza la arquitectura del proyecto, haciéndolo más modular y más fácil de mantener y ampliar a largo plazo. Aunque requiere algunos ajustes en los flujos de trabajo de los usuarios, especialmente en torno a la importación de datos, sienta las bases para el desarrollo futuro de esta potente herramienta contable.
