꼭 알아야 할 필수 Beancount 내장 플러그인

2026년 1월 2일 · 약 9분

Mike Thrift

Marketing Manager

Beancount의 강력함은 단순한 텍스트 형식뿐만 아니라 플러그인을 통한 확장성에도 있습니다. 기본 플러그인은 Beancount의 기능을 향상시키고, 번거로운 작업을 자동화하며, 회계 모범 사례를 준수하도록 돕는 내장 모듈입니다. 이 종합 가이드에서는 Beancount에서 제공하는 모든 기본 플러그인과 이를 효과적으로 사용하는 방법을 살펴봅니다.

Beancount 플러그인이란 무엇인가요?

Beancount 플러그인은 원장 항목을 처리하여 자동화, 검증 또는 변환 기능을 추가하는 Python 모듈입니다. 이들은 원장 파일을 로드하는 단계에서 실행되며 다음과 같은 역할을 수행할 수 있습니다:

반복적인 작업 자동화 (예: 계정 선언 생성)
데이터 무결성 검증 (예: 중복 거래 확인)
항목 변환 (예: 거래에서 가격 항목 생성)
회계 규칙 강제 (예: 계정당 하나의 통화 사용)

플러그인 사용 방법

Beancount 파일에서 플러그인을 활성화하려면 원장 상단에 plugin 지시어를 추가하세요:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

일부 플러그인은 설정 옵션을 허용합니다:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

기본 플러그인 카테고리

Beancount의 기본 플러그인은 크게 네 가지 카테고리로 나뉩니다:

1. 자동화 플러그인 (Automation Plugins)

2. 검증 플러그인 (Validation Plugins)

3. 변환 플러그인 (Transformation Plugins)

4. 메타 플러그인 (Meta-Plugins)

1. 자동화 플러그인

이 플러그인들은 반복적인 장부 정리 작업을 자동화하여 시간을 절약하고 수동 실수를 줄여줍니다.

`auto_accounts` - 자동 계정 선언

기능: 거래에는 나타나지만 명시적으로 선언되지 않은 계정에 대해 Open 지시어를 자동으로 삽입합니다.

사용 이유: 모든 계정을 사용하기 전에 수동으로 선언할 필요가 없습니다. 빠르게 시작하고 싶거나 보일러플레이트 코드를 최소화하려는 사용자에게 적합합니다.

예시:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "커피숍"
  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

; 다음 계정들은 자동으로 닫힙니다:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

사용 시기: 계정 계층 구조를 재구성하거나 특정 카테고리의 계정을 한꺼번에 닫을 때 사용합니다.

`implicit_prices` - 자동 가격 항목 생성

기능: 비용(@) 또는 가격(@@)이 포함된 거래 포스팅에서 Price 지시어를 생성합니다.

사용 이유: 거래 내역을 바탕으로 가격 데이터베이스를 자동으로 구축하여, 수동으로 가격을 입력하지 않고도 정확한 시장 가치 보고서를 생성할 수 있게 합니다.

예시:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "AAPL 주식 매수"
  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 * "임대료 납부"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; 이 항목은 오류를 발생시킵니다:
2026-01-02 * "임대료 납부"
  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

; 통화 선언이 없으면 다음 거래는 오류를 발생시킵니다:
2026-01-02 * "비트코인 매수"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

사용 시기: 엄격한 통화 추적을 유지하고 티커 심볼의 오타를 방지하려는 경우 권장됩니다.

`check_average_cost` - 원가 기준 검증

기능: 특히 평균 단가 부킹(average-cost booking)을 사용할 때, 거래에서 취득 원가가 제대로 유지되는지 확인합니다.

사용 이유: 세무 보고 및 자본 이득 계산을 위해 원가 회계가 정확하게 유지되도록 보장합니다.

사용 시기: 투자 포트폴리오나 정확한 원가 추적이 중요한 모든 상황에서 필수적입니다.

`check_closing` - 잔액 마감 검증

기능: 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                15000.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` - 계정당 단일 상품

기능: 각 계정이 한 가지 종류의 상품(commodity)만 보유하도록 강제합니다.

사용 이유: 동일한 계정에 서로 다른 자산이 섞이는 것을 방지하며, 이는 일반적으로 회계상의 모범 사례입니다.

예시:

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` - 자본 이득 검증

기능: 선언된 자본 이득을 랏(lot) 매도에서 계산된 이득과 교차 확인하여 손익 계산이 정확한지 보장합니다.

사용 이유: 수동 자본 이득 계산의 오류를 잡아내며, 정확한 세무 보고를 위해 중요합니다.

예시:

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` - 가격 고유성 확인

기능: 날짜별, 상품별로 하나의 가격 항목만 있는지 확인합니다.

사용 이유: 잘못된 가치 평가로 이어질 수 있는 충돌하는 가격 데이터를 방지합니다.

사용 시기: 가격을 수동으로 입력하거나 여러 가격 소스에서 가져올 때 권장됩니다.

3. 변환 플러그인 (Transformation Plugins)

이 플러그인들은 장부 데이터를 유용한 방식으로 수정하거나 강화합니다.

`currency_accounts` - 통화 거래 계정

기능: 외환 환전을 명시적으로 추적하기 위한 통화 거래 계정을 구현합니다.

사용 이유: 통화 변환 거래에 대한 상세한 추적을 제공하며, 이를 요구하는 회계 기준에 유용합니다.

사용 시기: 외환 차익/차손을 별도로 추적해야 하거나 특정 회계 요건을 충족해야 할 때 사용합니다.

`commodity_attr` - 상품 속성 검증

기능: 상품 지시어(commodity directives)에 필요한 속성(export, name 등)이 있는지 검증합니다.

사용 이유: 상품 메타데이터가 완전하고 일관되게 유지되도록 합니다.

사용 시기: 보고 또는 내보내기 목적으로 상세한 상품 메타데이터를 유지 관리할 때 사용합니다.

4. 메타 플러그인

이 플러그인들은 편의를 위해 다른 플러그인들을 모아놓은 컬렉션입니다.

`auto` - 모든 자동화 플러그인

기능: 한 번의 지시어로 "유연한(lax)" 또는 자동화된 플러그인 모음을 활성화합니다.

사용 시기: 최소한의 설정으로 최대한의 자동화를 원하는 사용자를 위한 빠른 설정 시.

`pedantic` - 모든 검증 플러그인

기능: 모든 엄격한 검증 플러그인을 한 번에 활성화합니다.

사용 이유: 데이터 무결성을 극대화하고 회계의 엄격함을 강화합니다. 실무용 장부나 정확성이 가장 중요한 경우에 적합합니다.

예시:

plugin "beancount.plugins.pedantic"

; 다음 플러그인들을 활성화하는 것과 동일합니다:
; - 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"

이는 빠른 시작을 위해 사용 편의성과 기능 사이의 훌륭한 균형을 제공합니다.

모범 사례

최소한으로 시작하고 필요에 따라 추가하기: auto_accounts와 noduplicates로 시작한 다음, 장부가 성숙해짐에 따라 검증 플러그인을 추가하세요.
플러그인 개별 테스트: 여러 플러그인을 추가할 때는 효과를 파악하기 위해 하나씩 활성화하세요.
오류 메시지 주의 깊게 읽기: 플러그인 오류는 종종 수정이 필요한 실제 회계 문제를 지적합니다.
실무용으로 pedantic 사용: 워크플로우가 정립되면 엄격한 검증 활성화를 고려하세요.
커스텀 플러그인과 결합: 기본 플러그인은 기능을 극대화하기 위해 forecast 플러그인과 같은 커스텀 플러그인과 함께 사용할 수 있습니다.

기본 플러그인 그 이상

기본 플러그인이 핵심 기능을 제공하는 동안, Beancount 생태계에는 특수한 요구 사항을 위한 많은 커뮤니티 개발 플러그인이 포함되어 있습니다:

fava.plugins.forecast - 반복 거래 예측용
fava.plugins.link_documents - 거래를 영수증 파일에 연결하기 위함
은행별 CSV 형식을 위한 커스텀 임포터
세금 전용 계산기 및 보고서

더 많은 옵션을 보려면 Beancount 생태계를 살펴보세요.

결론

Beancount의 기본 플러그인은 텍스트 기반 회계를 수동 프로세스에서 자동화되고 검증된 강력한 재무 관리 시스템으로 변화시킵니다. 이러한 내장 도구를 이해하고 활용하면 다음과 같은 이점이 있습니다:

✅ 지루한 장부 정리 작업 자동화
✅ 문제가 되기 전에 오류 포착
✅ 엄격한 데이터 무결성 유지
✅ 정확한 재무 보고서 생성
✅ 데이터 입력보다는 재무적 통찰력에 집중

오늘 바로 장부에서 이러한 플러그인들을 실험해 보세요. auto_accounts와 implicit_prices로 시작하여, 회계 관행이 성숙해짐에 따라 점진적으로 검증 플러그인을 추가해 보세요.

이 플러그인들을 사용해 볼 준비가 되셨나요? 지금 바로 Beancount.io로 이동하여 장부 파일에서 사용해 보세요!

출처

Beancount 플러그인에 대해 궁금한 점이 있으신가요? 커뮤니티 포럼에서 토론에 참여하거나 문서를 확인해 보세요.

References:

Share on Twitter Follow @beancount_io

Beancount 플러그인이란 무엇인가요?​

플러그인 사용 방법​

기본 플러그인 카테고리​

1. 자동화 플러그인 (Automation Plugins)​

2. 검증 플러그인 (Validation Plugins)​

3. 변환 플러그인 (Transformation Plugins)​

4. 메타 플러그인 (Meta-Plugins)​

1. 자동화 플러그인​

auto_accounts - 자동 계정 선언​

close_tree - 자동 계정 계층 구조 닫기​

implicit_prices - 자동 가격 항목 생성​

2. 검증 플러그인​

noduplicates - 중복 거래 감지​

check_commodity - 통화 선언 검증​

check_average_cost - 원가 기준 검증​

check_closing - 잔액 마감 검증​

coherent_cost - 통화/원가 일관성 확인​

leafonly - 리프 계정 강제​

nounused - 미사용 계정 탐지​

onecommodity - 계정당 단일 상품​

sellgains - 자본 이득 검증​

unique_prices - 가격 고유성 확인​

3. 변환 플러그인 (Transformation Plugins)​

currency_accounts - 통화 거래 계정​

commodity_attr - 상품 속성 검증​

4. 메타 플러그인​

auto - 모든 자동화 플러그인​

pedantic - 모든 검증 플러그인​

권장 플러그인 설정​

입문자용​

투자자용​

엄격한 회계용​

Beancount.io 기본 설정​

모범 사례​

기본 플러그인 그 이상​

결론​

출처​

Beancount.io 시작하기

시작하기

주요 기능

커뮤니티

법적 고지

Beancount 플러그인이란 무엇인가요?

플러그인 사용 방법

기본 플러그인 카테고리

1. 자동화 플러그인 (Automation Plugins)

2. 검증 플러그인 (Validation Plugins)

3. 변환 플러그인 (Transformation Plugins)

4. 메타 플러그인 (Meta-Plugins)

1. 자동화 플러그인

`auto_accounts` - 자동 계정 선언

`close_tree` - 자동 계정 계층 구조 닫기

`implicit_prices` - 자동 가격 항목 생성

2. 검증 플러그인

`noduplicates` - 중복 거래 감지

`check_commodity` - 통화 선언 검증

`check_average_cost` - 원가 기준 검증

`check_closing` - 잔액 마감 검증

`coherent_cost` - 통화/원가 일관성 확인

`leafonly` - 리프 계정 강제

`nounused` - 미사용 계정 탐지

`onecommodity` - 계정당 단일 상품

`sellgains` - 자본 이득 검증

`unique_prices` - 가격 고유성 확인

3. 변환 플러그인 (Transformation Plugins)

`currency_accounts` - 통화 거래 계정

`commodity_attr` - 상품 속성 검증

4. 메타 플러그인

`auto` - 모든 자동화 플러그인

`pedantic` - 모든 검증 플러그인

권장 플러그인 설정

입문자용

투자자용

엄격한 회계용

Beancount.io 기본 설정

모범 사례

기본 플러그인 그 이상

결론

출처