옵션 구성

Beancount의 동작은 기본 원장 파일 상단에 배치된 option 지시어로 사용자 정의됩니다. 이러한 키-값 쌍은 루트 계정 이름, 거래가 허용할 불균형 정도, 실행할 확장 기능을 제어합니다. ⚙️

이 페이지의 모든 옵션은 Beancount 3.2.3에 대해 로드되었으며, 인용된 모든 오류 메시지는 해당 버전이 출력하는 것입니다. Beancount는 인식하지 못하는 옵션을 거부합니다 — option "default_tolerance" "USD:0.01"은 Invalid option: 'default_tolerance' 오류로 실패합니다 — 따라서 이전 가이드에서 복사한 옵션은 조용히 실패하지 않습니다. 여기서 무엇이든 변경한 후에는 파일에서 bean-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_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'. 로드 오류를 보고하므로 bean-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으로 대체되었습니다.

세 가지 더 많은 옵션은 여전히 작동하지만 사용 중단 오류를 보고하며, 이는 bean-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 원장을 위한 견고한 기반을 제공하여 명확한 보고, 합리적인 정밀도 제어 및 논리적인 자본 계정 구조를 보장합니다.