2026-09-15 기준 최신 정보.
Beancount의 강점은 단순히 일반 텍스트 형식에 있는 것이 아니라 플러그인을 통한 확장성에 있습니다. 기본 플러그인은 Beancount의 기능을 향상시키고 지루한 작업을 자동화하며 회계 모범 사례를 적용하는 내장 모듈입니다. 이 종합 가이드에서는 Beancount에서 사용할 수 있는 모든 기본 플러그인과 이를 효과적으로 사용하는 방법을 살펴보겠습니다.
이 플러그인이 작동하는 지시문 구문에 대한 자세한 내용은 Beancount 구문 참조를 참조하세요. 플러그인과 importer 및 Fava를 결합하는 실제 커뮤니티 워크플로우는 커뮤니티 쇼케이스를 참조하세요. 플러그인과 상호작용하는 원장 옵션은 옵션 구성에 있습니다.
Beancount 플러그인이란?
Beancount 플러그인은 원장 항목을 처리하여 자동화, 검증 또는 변환 기능을 추가하는 Python 모듈입니다. 원장 파일을 로드하는 동안 실행되며 다음을 수행할 수 있습니다.
- 자동화 반복 작업 (예: 계정 선언 자동 생성)
- 검증 데이터 무결성 (예: 중복 거래 확인)
- 변환 항목 (예: 거래에서 가격 항목 생성)
- 적용 회계 규칙 (예: 계정당 단일 상품)
플러그인 사용 방법
Beancount 파일에서 플러그인을 활성화하려면 원장 상단에 plugin 지시문을 추가하세요:
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"일부 플러그인은 구성 옵션을 허용합니다:
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"기본 플러그인 분류
Beancount의 기본 플러그인은 네 가지 주요 범주로 나뉩니다:
1. 자동화 플러그인
2. 검증 플러그인
3. 변환 플러그인
4. 메타 플러그인
1. 자동화 플러그인
이 플러그인들은 반복적인 회계 작업을 자동화하여 시간을 절약하고 수동 오류를 줄여줍니다.
auto_accounts - 자동 계정 선언
기능: 명시적으로 선언되지 않았지만 거래에 나타나는 계정에 대한 Open 지시문을 자동으로 삽입합니다.
사용 이유: 사용하기 전에 모든 계정을 수동으로 선언할 필요가 없습니다. 빠르게 시작하거나 최소한의 보일러플레이트를 선호하는 사용자에게 적합합니다.
예시:
plugin "beancount.plugins.auto_accounts"
2026-01-01 * "Coffee shop"
Expenses:Food:Coffee 4.50 USD
Assets:Cash -4.50 USD플러그인이 없으면 수동으로 추가해야 합니다:
2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash사용 시기: 초보자 또는 덜 장황한 원장을 원하는 사람에게 이상적입니다. 그러나 명시적인 계정 선언은 오타를 잡는 데 도움이 될 수 있습니다.
close_tree - 자동 계정 계층 구조 닫기
기능: 상위 계정을 닫으면 이 플러그인이 모든 하위 계정을 자동으로 닫습니다.
사용 이유: 계정 계층 구조의 일관성을 유지합니다. Assets:Investments를 닫으면 Assets:Investments:Stocks 및 Assets:Investments:Bonds와 같은 모든 하위 계정이 자동으로 닫힙니다.
예시:
plugin "beancount.plugins.close_tree"
2025-06-30 close Assets:Investments
; These will be automatically closed:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate사용 시기: 계정 계층 구조를 재구성하거나 전체 계정 범주를 닫을 때.
implicit_prices - 자동 가격 항목 생성
기능: 비용(@) 또는 총액(@@)이 포함된 거래 게시물에서 Price 지시문을 합성합니다.
사용 이유: 거래에서 가격 데이터베이스를 자동으로 채워 수동 가격 입력 없이 정확한 시장 가치 보고를 가능하게 합니다.
예시:
plugin "beancount.plugins.implicit_prices"
2026-01-02 * "Buy AAPL shares"
Assets:Investments:Stocks 10 AAPL @ 150.00 USD
Assets:Cash -1500.00 USD이렇게 하면 자동으로 다음이 생성됩니다:
2026-01-02 price AAPL 150.00 USD사용 시기: 투자 추적 및 자동 가격 이력을 원하는 다중 통화 회계에 필수적입니다.
2. 검증 플러그인
이 플러그인들은 데이터 무결성과 회계 모범 사례를 적용하여 오류가 문제가 되기 전에 잡아냅니다.
noduplicates - 중복 거래 감지
기능: 거래 데이터의 해시를 계산하고 비교하여 두 개의 동일한 거래가 없는지 확인합니다.
사용 이유: 특히 여러 소스에서 거래를 가져올 때 실수로 인한 중복 항목을 방지합니다.
예시:
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 USD사용 시기: 은행 명세서에서 가져오거나 여러 데이터 소스를 사용하는 경우 항상 권장됩니다.
check_commodity - 상품 선언 검증
기능: 원장에서 사용되는 모든 상품에 해당 Commodity 지시문이 있는지 확인합니다.
사용 이유: 명시적인 상품 선언을 적용하여 자산과 통화의 깨끗한 목록을 유지하는 데 도움이 됩니다.
예시:
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 USD사용 시기: 엄격한 상품 추적을 유지하고 티커 심볼의 오타를 방지하는 데 권장됩니다.
check_average_cost - 원가 기준 검증
기능: 특히 평균 원가 결제 방식을 사용할 때 거래에서 원가 기준이 제대로 보존되는지 확인합니다.
사용 이유: 세금 신고 및 자본 이득 계산을 위해 정확한 원가 회계가 유지되도록 합니다.
사용 시기: 투자 포트폴리오 및 정확한 원가 추적이 중요한 모든 시나리오에 중요합니다.
check_closing - 잔액 마감 검증
기능: 마감 메타데이터를 잔액 확인으로 확장하여 마감 거래 후 포지션이 0인지 확인합니다.
사용 이유: 전체 포지션을 매도할 때 잔액이 실제로 0인지(남은 분수 주식이 없는지) 확인합니다.
예시:
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 USD#closing 태그는 이 거래 후 AAPL 포지션이 0인지 확인하도록 플러그인에 지시합니다.
사용 시기: 전체 포지션을 매도할 때 아무것도 남지 않도록 하기 위해.
coherent_cost - 통화/원가 일관성 검사
기능: 통화가 비용 주석 유무와 관계없이 일관되지 않게 사용되지 않는지 검증합니다.
사용 이유: 일반 통화(예: 100 USD)와 비용이 있는 통화(예: 100 USD {1.2 CAD})를 혼합하는 것을 방지하여 회계 오류를 유발할 수 있습니다.
사용 시기: 다중 통화 원장에서 일관성을 유지하는 데 권장됩니다.
leafonly - 말단 계정 강제
기능: 말단 계정(자식이 없는 계정)만 게시물을 받도록 합니다.
사용 이유: Expenses:Food와 같은 요약 계정에 직접 게시물이 없고 Expenses:Food:Groceries 및 Expenses:Food:Restaurants와 같은 하위 계정에만 게시물이 있는 깨끗한 계정 계층 구조를 적용합니다.
예시:
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 USD사용 시기: 명확한 분류로 엄격한 계층적 회계를 유지하려는 경우.
nounused - 미사용 계정 감지
기능: 열렸지만 실제로 거래에 사용되지 않은 계정을 식별합니다.
사용 이유: 계정 선언을 정리하고 잠재적인 오타나 사용되지 않는 계정을 식별하는 데 도움이 됩니다.
사용 시기: 계정 구조를 정기적으로 감사하고 정리할 때.
onecommodity - 계정당 단일 상품
기능: 각 계정이 한 가지 유형의 상품만 보유하도록 강제합니다.
사용 이유: 일반적으로 회계 모범 사례인 동일한 계정에서 다른 자산을 혼합하는 것을 방지합니다.
예시:
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 USD사용 시기: 엄격한 계정 분리를 선호하는 경우(주식/자산당 계정 하나).
sellgains - 자본 이득 검증
기능: 선언된 자본 이득과 롯 판매에서 계산된 이득을 교차 확인하여 손익 계산이 정확한지 확인합니다.
사용 이유: 수동 자본 이득 계산의 오류를 잡아내며 정확한 세금 신고에 중요합니다.
예시:
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 correct플러그인은 판매 수익(1500) - 원가 기준(1400) = 이득(100)을 확인합니다.
사용 시기: 자본 이득이 중요한 주식, 암호화폐 또는 기타 자산을 거래하는 사람에게 필수적입니다.
unique_prices - 가격 고유성 검사
기능: 상품 및 날짜별로 가격 항목이 하나만 있는지 확인합니다.
사용 이유: 잘못된 평가로 이어질 수 있는 상충되는 가격 데이터를 방지합니다.
사용 시기: 수동으로 가격을 입력하거나 여러 가격 소스에서 가져올 때 권장됩니다.
check_drained - 잔액 소진 계정 검증
기능: 이체나 마감 후 비어 있어야 할 계정에 잔액(가격이 없는 통화나 남은 롯 포함)이 남아 있는 계정을 표시합니다.
사용 이유: balance 단언과 #closing 태그가 놓칠 수 있는 잔여 잔액을 잡아냅니다. 특히 다중 상품 이체 후에 유용합니다.
상태(2026-09-15 확인): 현재 PyPI 라인(3.2.3)의 beancount/plugins/check_drained.py에 Beancount 3.x 트리에 존재합니다.
사용 시기: 대규모 포트폴리오 재구성 후 또는 브로커 계정을 닫을 때.
3. 변환 플러그인
이 플러그인들은 원장 데이터를 유용한 방식으로 수정하거나 향상시킵니다.
currency_accounts - 통화 거래 계정
기능: 외환 거래를 명시적으로 추적하기 위한 통화 거래 계정을 구현합니다.
사용 이유: 통화 변환 거래에 대한 상세한 추적을 제공하며 이를 요구하는 회계 표준에 유용합니다.
사용 시기: 외환 손익을 별도로 추적하거나 특정 회계 요구 사항을 충족해야 할 때.
commodity_attr - 상품 속성 검증
기능: 상품 지시문에 필수 속성(예: export, name 등)이 있는지 검증합니다.
사용 이유: 상품 메타데이터가 완전하고 일관되도록 합니다.
사용 시기: 보고 또는 내보내기 목적으로 자세한 상품 메타데이터를 유지할 때.
4. 메타 플러그인
이 플러그인은 편의를 위해 다른 플러그인을 모아 놓은 것입니다.
auto - 모든 자동 플러그인
기능: 하나의 지시문으로 "느슨한" 또는 자동 플러그인 모음을 활성화합니다.
사용 시기: 최소한의 구성으로 최대 자동화를 원하는 사용자를 위한 빠른 설정.
pedantic - 모든 검증 플러그인
기능: 모든 엄격한 검증 플러그인을 한 번에 활성화합니다.
사용 이유: 최대 데이터 무결성과 회계 엄격성을 적용합니다. 프로덕션 원장이나 정확성이 가장 중요한 경우에 좋습니다.
예시:
plugin "beancount.plugins.pedantic"
; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices사용 시기: 최대 검증을 원하고 더 엄격한 회계 관행을 유지할 의향이 있는 프로덕션 원장의 경우.
권장 플러그인 구성
초보자용
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"이 최소 세트는 일반적인 오류를 방지하면서 자동화를 제공합니다.
투자자용
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"투자 추적 및 자본 이득 정확성에 중점을 둡니다.
엄격한 회계용
plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"프로덕션 환경을 위한 최대 검증.
Beancount.io의 기본 구성
Beancount.io에서는 모든 새 원장 파일에 auto_accounts 플러그인을 기본으로 포함합니다:
plugin "beancount.plugins.auto_accounts"이것은 빠르게 시작하기 위한 사용 용이성과 기능 사이의 훌륭한 균형을 제공합니다.
플러그인 상태 2026-09-15 확인
Beancount 3.2.3 (PyPI, 2026-09-15)의 라이브 beancount/plugins 트리 기준:
| 플러그인 모듈 | 여전히 존재 | 참고 |
|---|---|---|
auto_accounts, close_tree, implicit_prices | 예 | 자동화 세트 변경 없음 |
noduplicates, check_commodity, check_average_cost, check_closing, coherent_cost, leafonly, nounused, onecommodity, sellgains, unique_prices | 예 | 검증 세트 변경 없음 |
currency_accounts, commodity_attr | 예 | 변환 세트 변경 없음 |
auto, pedantic | 예 | 메타 플러그인 변경 없음 |
check_drained | 예 | 위에 문서화됨; 이전 가이드에서 놓치기 쉬웠음 |
이 가이드의 원래 초안과 위 날짜 사이에 네이티브 세트에서 제거된 항목은 없습니다. 커뮤니티(비기본) 플러그인은 여전히 Awesome Beancount 플러그인 목록과 커뮤니티 쇼케이스에 속하며, 타사 저장소는 독립적으로 버전이 관리되므로 프로덕션 원장에서 활성화하기 전에 각 저장소의 최신 릴리스를 확인하세요.
모범 사례
-
최소한으로 시작하고 필요에 따라 추가:
auto_accounts와noduplicates로 시작한 다음 원장이 성숙해짐에 따라 검증 플러그인을 추가하세요. -
플러그인을 개별적으로 테스트: 여러 플러그인을 추가할 때는 한 번에 하나씩 활성화하여 그 효과를 이해하세요.
-
오류 메시지를 주의 깊게 읽으세요: 플러그인 오류는 종종 수정해야 할 실제 회계 문제를 가리킵니다.
-
프로덕션에는
pedantic사용: 워크플로우가 확립되면 엄격한 검증을 활성화하는 것을 고려하세요. -
사용자 정의 플러그인과 결합: 기본 플러그인은 예측 플러그인과 같은 사용자 정의 플러그인과 함께 작동하여 최대 기능을 제공합니다.
기본 플러그인 너머
기본 플러그인이 핵심 기능을 제공하지만 Beancount 생태계에는 특수 요구 사항을 위한 많은 커뮤니티 개발 플러그인이 있습니다:
- fava.plugins.forecast - 반복 거래 예측용
- fava.plugins.link_documents - 거래를 영수증 파일에 연결용
- 은행별 CSV 형식용 사용자 정의 importer
- 세금 관련 계산기 및 보고서
더 많은 옵션은 Beancount 생태계를, 사람들이 기본 플러그인을 importer 및 Fava와 결합하는 방법은 커뮤니티 쇼케이스를 확인하세요.
결론
Beancount의 기본 플러그인은 일반 텍스트 회계를 수동 프로세스에서 자동화되고 검증되며 강력한 재무 관리 시스템으로 변환합니다. 이러한 내장 도구를 이해하고 활용함으로써 다음을 수행할 수 있습니다:
- ✅ 지루한 회계 작업 자동화
- ✅ 문제가 되기 전에 오류 잡기
- ✅ 엄격한 데이터 무결성 유지
- ✅ 정확한 재무 보고서 생성
- ✅ 데이터 입력보다 재무 인사이트에 집중
오늘 원장에서 이러한 플러그인을 실험해 보세요. auto_accounts와 implicit_prices로 시작한 다음 회계 관행이 성숙함에 따라 검증 플러그인을 점진적으로 추가하세요.
이 플러그인들을 사용해 보시겠습니까? Beancount.io를 방문하여 오늘 원장 파일에서 사용해 보세요!
출처
- Beancount 플러그인 API 참조
- Beancount 스크립팅 및 플러그인 가이드
- Bryan Alves의 Beancount 플러그인 및 옵션
- Beancount GitHub 저장소
Beancount 플러그인에 대해 질문이 있으신가요? 커뮤니티 포럼에서 토론에 참여하거나 문서를 확인하세요.
라이브 암호화폐 예제 원장을 살펴보세요:
