Fava Options

Fava's behavior can be customized using custom "fava-option" directives in your Beancount ledger files. These directives allow you to control display settings, navigation, file management, and more — all without leaving your plain-text accounting workflow.

Syntax

Each Fava option is set with a Beancount custom directive:

YYYY-MM-DD custom "fava-option" "option-name" "value"

The date is required by Beancount's syntax but is ignored by Fava — you can use any valid date. For example:

2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "default-page" "income_statement/"

Display & Localization

language

Set the language for Fava's interface. When not set, Fava uses the browser's preferred language.

• Default: null (auto-detect from browser)
• Values: Any valid locale code (e.g., "en", "zh", "de", "fr", "es", "pt", "ru", "nl")

2000-01-01 custom "fava-option" "language" "en"

locale

Set the locale used for number formatting (thousands separators, decimal points). When not set, uses the language setting or browser locale.

• Default: null (uses language setting or browser locale)
• Values: Any valid locale string (e.g., "en_US", "de_DE", "zh_CN")

2000-01-01 custom "fava-option" "locale" "en_US"

Navigation & Layout

default-page

The page Fava shows when you navigate to a ledger without specifying a path.

• Default: "income_statement/"
• Values: Any valid Fava page path

2000-01-01 custom "fava-option" "default-page" "balance_sheet/"

Common page paths include: "income_statement/", "balance_sheet/", "trial_balance/", "journal/", "holdings/", "commodities/", "editor/".

fiscal-year-end

Set your fiscal year end date. This affects how Fava groups data by fiscal period rather than calendar year.

• Default: 12-31 (December 31, calendar year)
• Format: "MM-DD"

2000-01-01 custom "fava-option" "fiscal-year-end" "03-31"

This example sets the fiscal year to end on March 31, which is common for businesses in the UK, India, and Japan.

indent

The number of spaces used for indentation when auto-formatting entries.

• Default: 2
• Values: Any positive integer

2000-01-01 custom "fava-option" "indent" "4"

currency-column

The column at which currency amounts are aligned in the editor.

• Default: 61
• Values: Any positive integer

2000-01-01 custom "fava-option" "currency-column" "80"

Content Visibility

show-closed-accounts

Whether to display accounts that have been closed with a close directive.

• Default: false
• Values: "true" or "false"

2000-01-01 custom "fava-option" "show-closed-accounts" "true"

show-accounts-with-zero-transactions

Whether to display accounts that have zero transactions.

• Default: true
• Values: "true" or "false"

2000-01-01 custom "fava-option" "show-accounts-with-zero-transactions" "false"

show-accounts-with-zero-balance

Whether to display accounts with a zero balance on reports.

• Default: true
• Values: "true" or "false"

2000-01-01 custom "fava-option" "show-accounts-with-zero-balance" "false"

collapse-pattern

A regular expression pattern for account names that should be collapsed by default in the account tree. You can specify this option multiple times for multiple patterns.

• Default: [] (no patterns, nothing collapsed)
• Values: A regular expression string

2000-01-01 custom "fava-option" "collapse-pattern" "Assets:Investments:.*"
2000-01-01 custom "fava-option" "collapse-pattern" "Expenses:Food:.*"

sidebar-show-queries

The number of saved queries to display in the sidebar. Set to 0 to hide queries entirely.

• Default: 5
• Values: Any non-negative integer

2000-01-01 custom "fava-option" "sidebar-show-queries" "10"

File Management

default-file

The file that new entries are inserted into when using the editor. If not set, Fava uses the main ledger file.

• Default: null (main ledger file)
• Values: Path to a Beancount file

2000-01-01 custom "fava-option" "default-file" "/path/to/transactions.beancount"

insert-entry

A regular expression that controls where new entries are inserted in a file. Fava will insert entries before the first line matching this pattern.

• Default: null
• Values: A regular expression string

2000-01-01 custom "fava-option" "insert-entry" "^;; End of entries"

auto-reload

Whether Fava automatically reloads the ledger when changes are detected on disk.

• Default: false
• Values: "true" or "false"

2000-01-01 custom "fava-option" "auto-reload" "true"

use-external-editor

Whether to use an external editor instead of Fava's built-in editor. When enabled, source links open in the system's default editor.

• Default: false
• Values: "true" or "false"

2000-01-01 custom "fava-option" "use-external-editor" "true"

import-config

Path to the Beancount import configuration file for the import functionality.

• Default: null
• Values: Path to an import configuration file

2000-01-01 custom "fava-option" "import-config" "/path/to/import-config.py"

import-dirs

Directories to scan for files to import. Can be specified multiple times.

• Default: []
• Values: Path to a directory

2000-01-01 custom "fava-option" "import-dirs" "/path/to/bank-downloads"

Financial Display

unrealized

The account subtype used for unrealized gains and losses reporting.

• Default: "Unrealized"
• Values: Any valid account name component

2000-01-01 custom "fava-option" "unrealized" "Unrealized"

When set, Fava uses accounts like Income:Unrealized and Expenses:Unrealized for unrealized gains/losses.

invert-income-liabilities-equity

Whether to invert the sign of Income, Liabilities, and Equity accounts. When enabled, income is shown as positive and expenses as negative, which matches the common expectation.

• Default: false
• Values: "true" or "false"

2000-01-01 custom "fava-option" "invert-income-liabilities-equity" "true"

conversion-currencies

Currencies to display as conversion options in reports. Can be specified multiple times.

• Default: [] (uses operating currencies)
• Values: A currency code

2000-01-01 custom "fava-option" "conversion-currencies" "USD"
2000-01-01 custom "fava-option" "conversion-currencies" "EUR"

account-journal-include-children

Whether account journal pages should include transactions from child accounts.

• Default: true
• Values: "true" or "false"

2000-01-01 custom "fava-option" "account-journal-include-children" "false"

Monitoring

uptodate-indicator-grey-lookback-days

The number of days to look back when determining if an account is "up to date." Accounts with no transactions within this period will show a grey indicator.

• Default: 60
• Values: Any positive integer (number of days)

2000-01-01 custom "fava-option" "uptodate-indicator-grey-lookback-days" "90"

upcoming-events

The number of days into the future to show upcoming events.

• Default: 7
• Values: Any non-negative integer (number of days)

2000-01-01 custom "fava-option" "upcoming-events" "14"

Recommended Configuration

For most users, the following Fava options provide a good starting point:

; Display settings
2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "default-page" "income_statement/"

; Layout
2000-01-01 custom "fava-option" "indent" "2"
2000-01-01 custom "fava-option" "currency-column" "61"

; Content visibility
2000-01-01 custom "fava-option" "show-closed-accounts" "false"
2000-01-01 custom "fava-option" "sidebar-show-queries" "5"

; Financial display
2000-01-01 custom "fava-option" "invert-income-liabilities-equity" "false"

; Monitoring
2000-01-01 custom "fava-option" "upcoming-events" "7"
2000-01-01 custom "fava-option" "uptodate-indicator-grey-lookback-days" "60"

Viewing Your Current Options

You can view your current Fava options in the Beancount.io Dashboard by navigating to your ledger's Settings page. The "Fava Options" section displays all configured values, including defaults for any options you haven't explicitly set.

See Also

• Options Configuration — Beancount's core option directives
• UI Features — Customize the Beancount.io dashboard interface