2026-09-15 기준 최신 정보.
2024년 중반에 출시된 Beancount 버전 3은 널리 사용되는 일반 텍스트 회계 도구의 중요한 아키텍처 발전을 의미합니다. 사용자 원장 파일에 대한 이전 버전과의 호환성을 유지하면서도, 내부 구조와 관련 도구에는 상당한 변경이 있었습니다. 다음은 Beancount v3의 새로운 기능에 대한 분석입니다 — 그리고 이 가이드가 처음 게시된 이후 3.1–3.2 시리즈에 추가된 내용입니다.
구문 및 첫 원장에 대해서는 Beancount 구문 참조 및 시작하기를 참조하세요. check, query, import 및 reports를 래핑하는 호스팅 CLI에 대해서는 Beancount CLI 참조를 참조하세요.
더 모듈화되고 간소화된 아키텍처
Beancount v3에서 가장 중요한 변경 사항은 더 모듈화된 생태계로의 전환입니다. 이전에 핵심에 포함되어 있던 여러 주요 기능이 별도의 독립 프로젝트로 분리되었습니다. 이를 통해 Beancount의 핵심은 더 가벼워지고 개별 구성 요소에 대한 집중적인 개발이 가능해졌습니다.
이제 별도 패키지로 분리된 주요 구성 요소는 다음과 같습니다:
- beanquery: 원장 파일을 위한 강력한 SQL 유사 쿼리 도구가 이제 자체 패키지에 포함됩니다.
- beangulp: 이전
beancount.ingest모듈을 대체하는 데이터 가져오기 프레임워크의 새로운 위치입니다. - beanprice: 상품 및 주식의 가격을 가져오는 전용 도구입니다.
이러한 분리로 인해 사용자는 버전 2에서 사용하던 전체 기능을 유지하려면 beancount 자체 외에 이러한 패키지를 추가로 설치해야 합니다.
명령줄 도구 및 워크플로 변경 사항
새로운 모듈형 아키텍처를 반영하여 명령줄 도구에 몇 가지 주목할 만한 변경 사항이 있습니다:
bean-report가 제거됨: 이 도구는 제거되었습니다. 사용자는 이제 보고 요구 사항에beanquery패키지의bean-query를 사용하는 것이 좋습니다.- 새로운 Importer 워크플로:
bean-extract및bean-identify명령이 핵심에서 제거되었습니다.beangulp의 새로운 접근 방식은 스크립트 기반입니다. 사용자는 이제 은행 명세서와 같은 외부 소스에서 데이터를 가져오기 위한 자체 Python 스크립트를 만들어야 합니다.
구문 및 기능 개선 사항
핵심 회계 원칙은 동일하게 유지되지만, Beancount v3는 구문에 몇 가지 유용한 유연성을 도입합니다:
- 더 유연한 통화 코드: 통화 이름의 길이와 문자에 대한 이전 제한이 완화되었습니다. 이제 단일 문자 통화 기호가 지원됩니다.
- 확장된 트랜잭션 플래그: 사용자는 이제 A부터 Z까지의 모든 대문자를 트랜잭션 플래그로 사용할 수 있어 더 세분화된 분류가 가능합니다.
중요하게도, 이러한 변경 사항은 이전 버전과 호환되므로 기존 Beancount v2 원장 파일은 수정 없이 작동합니다.
C++ 재작성 및 성능
Beancount의 장기 목표 중 하나는 성능이 중요한 구성 요소를 C++로 재작성하는 것이었습니다. Beancount v3의 초기 릴리스에는 C++ 코어가 포함되지 않았으며, 2026-09-15 현재에도 여전히 그렇습니다: 게시된 PyPI 라인(3.2.3까지)은 여전히 모듈형 Python v3 브랜치입니다. 기존 C++/Bazel 작업은 별도의 cpp 브랜치에 있으며 사용자가 PyPI에서 설치하는 패키지의 일부가 아닙니다. 따라서 현재 v3 릴리스의 일상적인 성능은 후기 v2와 동일한 수준이며, C++ 재작성의 수십 배 성능 향상 대신 점진적인 파서 및 도구 개선이 이루어졌습니다.
이 문서 작성 이후 (v3.1 → v3.2.x)
주요 소스: 프로젝트 CHANGES 파일, 3.1.0…3.2.0 GitHub 비교 보기, 및 PyPI beancount(2026-09-15 기준 최신 3.2.3).
- 3.1.x 라인 — 3.0 모듈 분할(
beanquery,beangulp,beanprice는 별도 설치로 유지) 이후 지속적인 패키징 및 API 정리. - 3.2.0 (2025-09-14) —
beancount/beancount의 릴리스 커밋; 이 기간 동안 사용자에게 눈에 띄는 작업에는 다중 파일bean-format, 허용 오차/정밀도 개선, wheel/CI 유지 관리가 포함됩니다(위 비교 링크 참조). - 3.2.1–3.2.3 (2026) — 후속 바이너리 및 패키징 릴리스(메일링 리스트의 3.2.1 요약에 언급된 Python 3.14 테스트 커버리지 및 문서 스캐폴딩 포함).
pip install -U beancount로 설치하고 업그레이드 시 호환 도구(beanquery,beangulp)를 일치하는 메이저 버전으로 고정하세요.
Fava: Fava 1.30에 Beancount 3 지원이 추가되었습니다(2024-12-29). **Fava 1.30.13 (2026-05-19)**은 Beancount 2 지원을 중단하고 importers에 beangulp를 기대합니다. 2026-09-15 기준 현재 PyPI 라인은 1.30.16입니다. Fava 업그레이드는 Beancount 3 원장과 함께 진행하세요.
v2에서 v3으로 마이그레이션
대부분의 사용자에게 Beancount v2에서 v3으로의 마이그레이션은 비교적 간단합니다:
- 원장 파일:
.beancount파일은 변경할 필요가 없습니다. - 설치:
pip을 사용하여beanquery및beangulp와 같은 새 별도 패키지를 설치해야 합니다. - Importer 스크립트: 사용자 정의 importer가 있는 경우 새
beangulpAPI를 사용하도록 업데이트해야 합니다. 이는 주로 importer가 상속하는 기본 클래스를 변경하고 일부 메서드 시그니처를 조정하는 것을 포함합니다. - Fava: Beancount의 인기 웹 인터페이스인 Fava는 v3와 호환되도록 업데이트되었습니다. 원활한 경험을 위해 최신 버전의 Fava를 사용하고 있는지 확인하세요.
요컨대, Beancount v3는 프로젝트의 아키텍처를 간소화하고 더 모듈화하여 장기적으로 유지 관리 및 확장을 더 쉽게 만드는 기초 릴리스입니다. 특히 데이터 가져오기 주변의 사용자 워크플로에 일부 조정이 필요하지만, 이 강력한 회계 도구의 향후 개발을 위한 토대를 마련합니다.
