Beancount의 동작은 기본 원장 파일 상단에 배치된 option 지시어로 사용자 정의됩니다. 이러한 키-값 쌍은 루트 계정 이름, 거래가 허용할 불균형 정도, 실행할 확장 기능을 제어합니다. ⚙️
이 페이지의 모든 옵션은 Beancount 3.2.3에 대해 로드되었으며, 인용된 모든 오류 메시지는 해당 버전이 출력하는 것입니다. Beancount는 인식하지 못하는 옵션을 거부합니다 — option "default_tolerance" "USD:0.01"은 Invalid option: 'default_tolerance' 오류로 실패합니다 — 따라서 이전 가이드에서 복사한 옵션은 조용히 실패하지 않습니다. 여기서 무엇이든 변경한 후에는 파일에서 bea check를 실행하세요.
핵심 옵션 구성
이러한 옵션은 원장의 기본 설정을 제어합니다.
기본 설정
다음은 설정할 수 있는 가장 일반적인 옵션입니다.
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"title: 보고서 및 웹 인터페이스의 제목을 설정합니다. 기본값은Beancount입니다.render_commas: true로 설정하면 보고서의 숫자가 천 단위 구분 기호로 표시됩니다 (예:1,000,000.00). 기본값은 false입니다.1,TRUE,true또는yes중 하나는 true로 읽히며, 다른 모든 문자열은 false로 읽힙니다.plugin_processing_mode:default(기본값) 또는raw중 하나입니다. 다른 값은Error for option 'plugin_processing_mode'오류로 실패합니다.
raw는 default의 더 가벼운 버전이 아닙니다 — Beancount의 자체 처리 단계를 끄는 스위치입니다. default에서는 Beancount가 플러그인 전에 beancount.ops.documents를 실행하고, 그 후에 beancount.ops.pad와 beancount.ops.balance를 실행합니다. raw에서는 직접 나열한 플러그인만 실행되므로 pad 지시어는 적용되지 않고 balance 검증은 수행되지 않습니다:
; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
1970-01-02 * "Opening balance"
Assets:Cash 100.00 USD
Equity:Opening-Balances -100.00 USD
1970-01-03 balance Assets:Cash 999.00 USD해당 줄을 default로 변경하면 동일한 파일이 Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little) 오류를 보고합니다. raw는 의도적으로 해당 단계를 직접 다시 구현하는 경우에만 사용하세요.
계정 이름 사용자 정의
Beancount의 다섯 가지 기본 계정 유형의 이름을 변경할 수 있습니다. 이것은 단순한 표면적 변경이 아닙니다. 이 옵션은 파서가 허용하는 루트 이름을 재정의하므로 파일의 모든 계정은 새 이름을 사용해야 하며, 기존 이름은 유효하지 않게 됩니다.
option "name_assets" "Actifs"
option "name_expenses" "Depenses"
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
2024-01-02 * "Boulangerie" "Pain"
Depenses:Alimentation 4.20 EUR
Actifs:Banque:Courant -4.20 EUR이전 루트에 단일 게시물을 남기면 파일이 Invalid account name: Assets:Banque:Courant 오류로 로드를 중지합니다. 다섯 가지 옵션은 name_assets, name_liabilities, name_equity, name_income, name_expenses입니다. 각 값은 콜론이 없는 단일 대문자 단어여야 하며, 그렇지 않으면 Error for option 'name_assets': Invalid root account name 오류가 발생합니다. 원장을 시작할 때 루트 이름을 변경하세요. 중간에 변경하면 안 됩니다.
자본 계정 구성
Beancount는 기간을 요약할 때 여러 자본 계정을 합성합니다 — 기초 잔액, 이월 이익 및 통화 변환. 이러한 옵션은 해당 계정의 이름을 지정합니다.
각 값은 리프 이름이며, Beancount는 이를 name_equity 아래에 자동으로 결합합니다. 자본 루트를 직접 작성하면 Equity:Equity:Opening-Balances와 같은 잘못된 계정이 생성되며, 이는 의도한 계정과 다릅니다.
option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"| 옵션 | 기본 리프 | 결과 계정 |
|---|---|---|
account_previous_balances | Opening-Balances | Equity:Opening-Balances |
account_previous_earnings | Earnings:Previous | Equity:Earnings:Previous |
account_current_earnings | Earnings:Current | Equity:Earnings:Current |
account_previous_conversions | Conversions:Previous | Equity:Conversions:Previous |
account_current_conversions | Conversions:Current | Equity:Conversions:Current |
account_rounding은 이 그룹에서 예외입니다: 완전한 계정 이름을 사용하며 작성된 그대로 저장됩니다. 따라서 Equity:Rounding은 올바르며 이중 접두사가 아닙니다. 또한 기본적으로 설정되어 있지 않으며, Beancount 3.2.3에서 설정해도 로딩에는 영향을 미치지 않습니다 — 잔차 처리에 대한 자세한 내용은 정밀도 및 허용 오차를 참조하세요.
정밀도 및 허용 오차 설정
이러한 옵션은 Beancount가 거래에서 허용하는 불균형 정도를 제어합니다.
기본 허용 오차 구성
Beancount는 게시물의 소수 자릿수에서 허용 오차를 추론합니다. 이러한 세 가지 옵션은 해당 추론을 조정합니다.
option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"inferred_tolerance_default: 통화별 최소 허용 오차입니다. 구문은<currency>:<number>이며,*는 모든 통화를 한 번에 설정합니다. 여러 통화를 설정하려면 옵션을 반복하세요.tolerance_multiplier: 가장 작은 유효 숫자의 허용 오차 배율입니다. **기본값은0.5**입니다. 이는 백분율 증가가 아닙니다:1.2로 설정하면 모든 추론 허용 오차가 기본값의 2.4배가 됩니다.infer_tolerance_from_cost: true로 설정하면 원가로 보유한 게시물도 원가 통화의 허용 오차를 넓힙니다. 기본값은 꺼져 있습니다.
이전 이름 inferred_tolerance_multiplier는 여전히 동일한 값을 설정하지만 Renamed to 'tolerance_multiplier'. 로드 오류를 보고하므로 bea check는 해당 이름을 사용하는 파일에서 실패합니다. 이름을 변경하세요.
원가 기준 허용 오차
이 옵션은 원가로 보유한 게시물의 허용 오차 동작을 제어합니다.
; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"Beancount 3.2.3은 정확히 일곱 가지 이름을 허용합니다: STRICT (기본값), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO, AVERAGE. 다른 값은 로드 시 Error for option 'booking_method' 오류로 거부됩니다 — SIMPLE 및 FULL을 포함하며, 이는 예약 방법이 아니며 결코 아니었습니다. AVERAGE는 여기서 허용되지만 그 뒤에 구현이 없습니다; 이 방법으로 감소시키면 AVERAGE method is not supported 오류가 발생합니다. 재고 관리는 동일한 원장에서 일곱 가지 모두를 통해 작동합니다.
통화 관리
정확한 보고를 위해서는 통화 구성이 중요합니다.
운영 통화
운영 통화는 보고서에서 합계를 원하는 통화입니다. 하나 이상을 선언하려면 옵션을 반복하세요. 값은 이전 값을 대체하지 않고 누적됩니다.
option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"운영 통화를 선언하면 보고 도구가 각 통화에 대해 별도의 열을 제공합니다. conversion_currency는 Beancount가 변환을 기록하는 가상 통화의 이름을 지정합니다. 기본값은 NOTHING이며, 이를 설정하는 유일한 이유는 실제 통화로 사용하지 않는 다른 자리 표시자를 선택하기 위해서입니다.
문서 관리
Beancount는 거래를 영수증이나 송장과 같은 외부 파일에 연결할 수 있습니다. documents 옵션은 스캔할 폴더를 지정합니다.
option "documents" "/home/user/Documents/beancount"해당 블록의 경로는 예시입니다 — 실행하기 전에 자신의 경로로 대체하세요. 규칙은 엄격하며, 각 규칙을 위반하면 오류 대신 조용히 무시됩니다:
- 폴더는 존재해야 합니다. 존재하지 않으면
Document root '/no/such/place' does not exist오류로 로드가 실패합니다. - 하위 폴더는 계정 이름입니다.
Assets:US:BofA:Checking에 대한 명세서는<root>/Assets/US/BofA/Checking/에 있어야 합니다. 루트에 느슨하게 있는 파일은 무시됩니다. - 계정은 개설되어 있어야 합니다. 원장에서 개설하지 않은 계정 아래에서 발견된 문서는 경고 없이 건너뜁니다.
- 파일 이름은 날짜로 시작합니다,
YYYY-MM-DD.description.ext형식 (예:2025-07-28.amazon-order.pdf). 폴더의 다른 파일은 무시됩니다. - 경로는 기본 원장 파일에 대해 절대 또는 상대적일 수 있으며, 여러 폴더에 대해 옵션을 반복할 수 있습니다.
플러그인 시스템
Beancount의 기능은 플러그인으로 확장할 수 있습니다.
플러그인 구성
플러그인은 plugin이 아닌 독립적인 option 지시어로 로드됩니다. option "plugin" "..."는 Option 'plugin' may not be set 오류로 실패합니다.
plugin "beancount.plugins.auto_accounts"
2024-03-01 * "Coffee Shop" "Flat white"
Expenses:Food:Coffee 4.50 USD
Assets:US:BofA:Checking -4.50 USD해당 파일은 auto_accounts가 두 계정을 모두 열어주기 때문에 로드됩니다. plugin 줄을 삭제하면 Invalid reference to unknown account 'Expenses:Food:Coffee' 오류가 보고됩니다. 구성을 받는 플러그인은 두 번째 문자열로 받습니다: plugin "module" "config". 플러그인은 작성한 순서대로 실행되며, Beancount 자체의 documents 단계 이후, pad 및 balance 단계 이전에 실행됩니다 — plugin_processing_mode를 raw로 설정하지 않는 한, 이 경우 해당 단계는 완전히 제거됩니다.
기술적 한계 및 제약
이러한 옵션은 Beancount 파서의 기술적 측면을 제어합니다.
문자열 처리
여러 줄 문자열에 허용되는 줄 수를 제한할 수 있으므로, 종결되지 않은 따옴표는 파일 끝이 아닌 입력한 위치 근처에서 보고됩니다.
option "long_string_maxlines" "64"보간 정밀도
기본적으로 Beancount는 두 가지 다른 작업에 하나의 허용 오차를 사용합니다: 누락된 금액을 채우는 것과 거래 균형을 결정하는 것입니다. 이 옵션을 켜면 첫 번째 작업에는 가장 정밀한 추론 허용 오차를, 두 번째 작업에는 가장 느슨한 허용 오차를 사용하여 보간된 금액이 표류하는 것을 방지합니다.
option "use_precise_interpolation" "TRUE"게시물에 명시적 허용 오차를 지정하는 옵션은 없습니다. Beancount 3.2.3이 가진 유일한 명시적 허용 오차 구문은 balance 지시어의 물결표(~)입니다 — 4.271 ~ 0.01 RGAGX — 그리고 이를 위한 옵션은 필요 없습니다. 거래 게시물 내부의 물결표는 구문 오류입니다.
더 이상 사용되지 않거나 제거된 옵션
이전 가이드에서 여전히 권장하는 세 가지 옵션은 Beancount 3.2.3에 존재하지 않습니다. 이 블록의 모든 줄은 로드에 실패합니다:
option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"experiment_explicit_tolerances— 활성화했던 게시물 수준의~구문은 사라졌습니다. 대신balance지시어의 물결표를 사용하세요.use_legacy_fixed_tolerances— 고정된0.005/0.015허용 오차는 사라졌습니다. 허용 오차는 거래별로 추론되며,tolerance_multiplier및inferred_tolerance_default로 조정됩니다.default_tolerance— 균형 조정을 위한inferred_tolerance_default와 렌더링을 위한display_precision으로 대체되었습니다.
세 가지 더 많은 옵션은 여전히 작동하지만 사용 중단 오류를 보고하며, 이는 bea check를 실패시키기에 충분합니다:
inferred_tolerance_multiplier—tolerance_multiplier로 이름이 변경되었습니다.allow_pipe_separator— 수취인과 설명 사이의 이전|구분 기호를 허용합니다.allow_deprecated_none_for_tags_and_links— 태그와 링크가 있어야 할 위치에 리터럴None을 허용합니다.
Fava 옵션은 별개입니다
이 페이지의 모든 내용은 Beancount 자체에서 읽습니다. Fava의 자체 설정은 전혀 option 지시어가 아닙니다 — 날짜가 있는 custom "fava-option" 지시어이며, Beancount는 이를 무시합니다. Fava 설정을 option으로 작성하면 Invalid option 오류로 실패합니다. 해당 목록은 Fava 옵션을 참조하세요.
권장 구성 ✅
대부분의 사용자에게 다음 구성은 견고하고 합리적인 시작점을 제공합니다. 하나의 파일이며 로드됩니다.
; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"주석은 ;로 시작합니다. // 주석은 Beancount에서 구문 오류이며, 파일의 나머지 부분을 무너뜨립니다.
이 설정은 새 Beancount 원장을 위한 견고한 기반을 제공하여 명확한 보고, 합리적인 정밀도 제어 및 논리적인 자본 계정 구조를 보장합니다.