Atualizado em 15 de setembro de 2026.
O Beancount versão 3, lançado em meados de 2024, marca uma evolução arquitetural significativa para a popular ferramenta de contabilidade em texto plano. Embora mantenha compatibilidade retroativa para os arquivos de razão dos usuários, a estrutura subjacente e as ferramentas associadas passaram por mudanças substanciais. Aqui está um detalhamento do que há de novo no Beancount v3 — e o que foi adicionado na linha 3.1–3.2 desde que este guia foi publicado pela primeira vez.
Para sintaxe e primeiros razões, consulte a referência de sintaxe do Beancount e Introdução. Para o CLI hospedado que envolve check, query, import e relatórios, consulte a referência do CLI Beancount.
Uma Arquitetura Mais Modular e Simplificada
A mudança mais significativa no Beancount v3 é a transição para um ecossistema mais modular. Várias funcionalidades-chave que antes eram agrupadas com o núcleo foram separadas em projetos independentes. Isso torna o núcleo do Beancount mais enxuto e permite um desenvolvimento mais focado em componentes individuais.
Os principais componentes que agora são pacotes separados incluem:
- beanquery: A poderosa ferramenta de consulta estilo SQL para seus arquivos de razão agora está em seu próprio pacote.
- beangulp: Este é o novo lar do framework de importação de dados, substituindo o antigo módulo
beancount.ingest. - beanprice: Uma ferramenta dedicada para obter preços de commodities e ações.
Essa separação significa que os usuários precisarão instalar esses pacotes além do próprio beancount para manter a funcionalidade completa a que estavam acostumados na versão 2.
Mudanças nas Ferramentas de Linha de Comando e Fluxos de Trabalho
Refletindo a nova arquitetura modular, há algumas mudanças notáveis nas ferramentas de linha de comando:
bean-reportfoi removido: Esta ferramenta foi removida. Agora os usuários são incentivados a usarbean-query(do pacotebeanquery) para suas necessidades de relatórios.- Novo Fluxo de Trabalho de Importação: Os comandos
bean-extractebean-identifyforam removidos do núcleo. A nova abordagem combeangulpé baseada em scripts. Os usuários criarão agora seus próprios scripts Python para lidar com a importação de dados de fontes externas, como extratos bancários.
Aprimoramentos de Sintaxe e Recursos
Embora os princípios contábeis centrais permaneçam os mesmos, o Beancount v3 introduz alguma flexibilidade bem-vinda em sua sintaxe:
- Códigos de Moeda Mais Flexíveis: As restrições anteriores sobre o comprimento e caracteres para nomes de moedas foram relaxadas. Símbolos de moeda de um único caractere agora são suportados.
- Flags de Transação Expandidas: Os usuários agora podem usar qualquer letra maiúscula de A a Z como uma flag para transações, permitindo uma categorização mais granular.
Importante: essas mudanças são compatíveis retroativamente, então seus arquivos de razão existentes do Beancount v2 funcionarão sem modificações.
A Reescrita em C++ e Desempenho
Um dos objetivos de longo prazo para o Beancount tem sido uma reescrita de seus componentes críticos de desempenho em C++. O lançamento inicial do Beancount v3 não incluiu um núcleo em C++, e em 15 de setembro de 2026 isso continua verdadeiro: a linha publicada no PyPI (até 3.2.3) ainda é o ramo Python modular v3. O trabalho histórico em C++/Bazel vive em um ramo separado cpp e não faz parte dos pacotes que os usuários instalam do PyPI. O desempenho diário das versões atuais do v3 está, portanto, na mesma classe dos finais do v2, com melhorias incrementais no parser e nas ferramentas, em vez de uma reescrita em C++ de ordem de magnitude.
Desde que isto foi escrito (v3.1 → v3.2.x)
Fontes primárias: o arquivo CHANGES do projeto, visualizações de comparação no GitHub para 3.1.0…3.2.0 e PyPI beancount (última 3.2.3 em 15 de setembro de 2026).
- Linha 3.1.x — Continuação da limpeza de empacotamento e API após a divisão modular do 3.0 (
beanquery,beangulp,beanpricepermanecem como instalações separadas). - 3.2.0 (14 de setembro de 2025) — Commit de lançamento em
beancount/beancount; trabalho notável voltado ao usuário nesse período incluibean-formatmulti-arquivo, refinamentos de tolerância/precisão e manutenção de wheels/CI (veja o link de comparação acima). - 3.2.1–3.2.3 (2026) — Lançamentos binários e de empacotamento subsequentes (incluindo cobertura de testes do Python 3.14 e andamento da documentação mencionados no resumo do 3.2.1 na lista de discussão). Instale com
pip install -U beancounte fixe os companheiros (beanquery,beangulp) em versões principais correspondentes ao atualizar.
Fava: Fava 1.30 adicionou suporte ao Beancount 3 (29 de dezembro de 2024). Fava 1.30.13 (19 de maio de 2026) removeu o suporte ao Beancount 2 e espera beangulp para importadores. A linha atual no PyPI em 15 de setembro de 2026 é 1.30.16. Acompanhe as atualizações do Fava com um razão do Beancount 3.
Migrando do v2 para o v3
Para a maioria dos usuários, a migração do Beancount v2 para o v3 é relativamente direta:
- Arquivos de Razão: Nenhuma alteração é necessária em seus arquivos
.beancount. - Instalação: Você precisará instalar os novos pacotes separados, como
beanqueryebeangulp, usandopip. - Scripts de Importação: Se você tem importadores personalizados, precisará atualizá-los para usar a nova API do
beangulp. Isso envolve principalmente mudar a classe base da qual seus importadores herdam e ajustar algumas assinaturas de métodos. - Fava: A popular interface web para o Beancount, o Fava, foi atualizada para ser compatível com o v3. Garanta que você tenha a versão mais recente do Fava para uma experiência sem interrupções.
Em essência, o Beancount v3 é um lançamento fundamental que simplifica a arquitetura do projeto, tornando-o mais modular e mais fácil de manter e estender a longo prazo. Embora exija alguns ajustes nos fluxos de trabalho dos usuários, especialmente em torno da importação de dados, ele prepara o terreno para o desenvolvimento futuro desta poderosa ferramenta de contabilidade.
