Fava Options

Configure stock Fava with dated custom "fava-option" directives. These settings are separate from Beancount core options.

This reference was executed with Beancount 3.2.3, beanquery 0.2.0 and Fava 1.30.16. The matrix describes that stock release. Beancount.io has a separate dashboard and backend; its exposed settings do not prove that every stock Fava feature is available there.

Syntax​

Values are quoted strings, including integers and booleans. This complete example parses in both Beancount and Fava:

; Minimal Fava configuration
option "operating_currency" "USD"
2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "default-page" "income_statement/"
2000-01-01 custom "fava-option" "indent" "2"
2000-01-01 custom "fava-option" "show-closed-accounts" "false"

The date is required. Fava processes the loaded custom directives in date order; a later scalar setting replaces an earlier one. Repeated collapse-pattern, import-dirs and insert-entry settings accumulate. Insertion rules use their dates to choose a destination, so those dates are meaningful.

To reproduce the examples locally, install uv, then create a disposable environment:

uv venv .venv-fava-docs
uv pip install --python .venv-fava-docs/bin/python 'beancount==3.2.3' 'beanquery==0.2.0' 'fava==1.30.16'
source .venv-fava-docs/bin/activate
bean-check main.beancount
fava main.beancount

Create main.beancount from the configuration block first, or use an existing ledger. The shell commands above use POSIX paths. bean-check checks Beancount syntax and accounting; Fava additionally checks its own option names and values. Inspect Fava's Errors report as well.

The defaults below were read from the installed FavaOptions dataclass and checked against the versioned option parser. “Unset” means None; an empty collection means no configured entries. The value-type column describes the content of the quoted string.

Use "true" or "false" for booleans. The comparison is case-insensitive: "TRUE" also enables an option. Any string other than a case variant of "true" is treated as false. Its integer parser checks integer syntax, not a positive range; use positive layout sizes and non-negative counts.

Display & Localization​

language​

Sets the interface translation, for example "en", "de" or "zh_CN". When unset, Fava negotiates with the browser. The locale must have a translation shipped by Fava; a syntactically valid language code alone is insufficient.

locale​

Sets number formatting independently of interface language, for example "en_US" or "de_DE". Without this option, Fava uses its unlocalized number pattern. Core option "render_commas" "TRUE" supplies the en fallback. It does not inherit the browser language.

Navigation & Layout​

default-page​

Sets the destination within the ledger, such as "balance_sheet/" or "journal/?time=year". Copy the part after the ledger slug from a working stock Fava URL. Do not prepend /: report paths are relative to that ledger.

fiscal-year-end​

Sets fiscal time-filter boundaries. For example, "03-31" ends a fiscal year on March 31. It supports fiscal year and quarter filters; it does not change transaction dates. Fava also accepts month values above 12 to label a fiscal year ending in the next calendar year.

indent​

Sets posting indentation for generated entries and editor formatting. Use a positive integer string, such as "4".

currency-column​

Sets the currency alignment column when saving or aligning postings. It also positions the editor's vertical guide. The default is "61".

Content Visibility​

show-closed-accounts​

Includes closed accounts in report account trees. Accounts with non-zero balances remain visible regardless of this setting.

show-accounts-with-zero-transactions​

Includes accounts with no transactions in account trees. It does not suppress an account that has a non-zero balance.

show-accounts-with-zero-balance​

Includes accounts whose report balance is zero. Turn it off with "false" for a shorter tree.

collapse-pattern​

Matches account names to collapse in account trees. Repeat the directive for multiple patterns. For example, "^Assets:Investments" collapses that account and its descendants.

sidebar-show-queries​

Limits the number of saved queries linked in the sidebar. "0" hides those links. See custom links and queries.

show-metadata-indicators​

Shows the small metadata badges in journals. Set it to "false" to hide the badges without removing metadata from the ledger.

File Management​

default-file​

Chooses the file initially opened by the editor and the fallback destination for new entries. A relative path is resolved from the file containing the directive. With no value, the containing file is selected. Without this option, the main ledger file is the fallback. An existing file must also be included in the ledger to be an editable source.

insert-entry​

Places a new entry before a matching custom directive, in the file containing that directive. Its regex matches an account name from the start; it never searches raw file lines. Fava considers transaction postings from last to first. For the first account with an eligible match, it chooses the latest rule dated strictly before the new entry. If none matches, it appends to the default file. The insertion implementation is the authority for these rules.

Create these three files in the same directory. main.beancount supplies the accounts and includes:

; main.beancount
option "title" "Insertion Demo"
option "operating_currency" "USD"
include "january.beancount"
include "february.beancount"
2000-01-01 open Assets:Checking USD
2000-01-01 open Assets:Cash USD
2000-01-01 open Assets:Wallet USD
2000-01-01 open Expenses:Food USD
2000-01-01 custom "fava-option" "default-file"
2024-01-01 custom "fava-option" "insert-entry" "^Expenses:Food$"

january.beancount contains:

; january.beancount
2024-01-01 custom "fava-option" "insert-entry" "^Assets:Checking$"

february.beancount contains:

; february.beancount
2024-02-01 custom "fava-option" "insert-entry" "^Assets:Checking$"

Start Fava with main.beancount. Add these transactions through its transaction form; they are input to the insertion operation, not an extra file to include beforehand:

2024-01-15 * "January groceries"
  Expenses:Food       10.00 USD
  Assets:Checking    -10.00 USD
 
2024-02-01 * "Same-day boundary"
  Expenses:Food       20.00 USD
  Assets:Checking    -20.00 USD
 
2024-02-15 * "February groceries"
  Expenses:Food       30.00 USD
  Assets:Checking    -30.00 USD
 
2024-02-16 * "Cash groceries"
  Expenses:Food       40.00 USD
  Assets:Cash        -40.00 USD
 
2024-02-17 * "Unmatched cash transfer"
  Assets:Cash         50.00 USD
  Assets:Wallet      -50.00 USD

The first two entries go before the January rule. The third goes before the February rule. The fourth tries Assets:Cash, finds no match, then uses the Expenses:Food rule in the main file. The fifth has no matching account and appends to main.beancount. Saving a batch updates rule line numbers as entries are inserted.

auto-reload​

Reloads the page automatically when Fava detects an external source change. When false, Fava offers a reload notification. Changes made through Fava itself already trigger a reload.

use-external-editor​

Opens source links through the beancount:// URL scheme. Install a handler on the computer running the browser and ensure it can access the ledger files. This is not an automatic connection to files on a hosted server.

import-config​

Points to a Python importer configuration. This is an integration setting: create the configuration and install its importer dependencies before using the Import report. The three pinned packages above do not provide a bank importer configuration.

import-dirs​

Adds a directory to scan for import candidates. Repeat the directive to add directories. Use real accessible directories; setting the option does not create them.

Financial Display​

unrealized​

Not a stock Fava 1.30.16 option. Fava reports Unknown option followed by the name in backticks if you add it. Do not use it to configure stock unrealized-gain accounts.

The Beancount.io source snapshot reviewed on 2026-09-07 does expose a separate string field named unrealized, with default "Unrealized", in its backend option parser and dashboard Settings table. That verifies the field exists there. It does not establish that changing it creates Income:Unrealized or Expenses:Unrealized, or that a particular deployment runs this snapshot.

invert-income-liabilities-equity​

Flips the displayed signs of Income, Liabilities and Equity in the income statement and balance sheet. Expenses retain their signs. Journal entries, account journals and stored postings remain unchanged.

conversion-currencies​

Replaces the conversion dropdown choices with a space-separated list in one string:

; Conversion dropdown
2000-01-01 custom "fava-option" "conversion-currencies" "USD EUR"

Repeating this option replaces the previous list. When unset, Fava offers operating currencies plus commodities it recognizes as ISO 4217 currencies.

account-journal-include-children​

Includes child-account entries in an account's journal by default. Set it to "false" to start with only that account.

invert-gains-losses-colors​

Reverses the colors used for unrealized gains and losses in market-value balance-sheet and trial-balance views. It changes colors, not amounts or account names.

Monitoring​

uptodate-indicator-grey-lookback-days​

Controls the grey freshness indicator's lookback period. Enable account indicators with fava-uptodate-indication: TRUE on the account's open directive; see the UI metadata example.

upcoming-events​

Controls the sidebar notification count for upcoming events within the specified number of days. "0" disables the count.

Recommended Configuration​

This complete configuration is a starting point for the stock environment above. It changes display settings without loading plugins or requiring extra files:

option "operating_currency" "USD"
2000-01-01 custom "fava-option" "language" "en"
2000-01-01 custom "fava-option" "locale" "en_US"
2000-01-01 custom "fava-option" "default-page" "income_statement/"
2000-01-01 custom "fava-option" "fiscal-year-end" "12-31"
2000-01-01 custom "fava-option" "indent" "2"
2000-01-01 custom "fava-option" "currency-column" "61"
2000-01-01 custom "fava-option" "show-closed-accounts" "false"
2000-01-01 custom "fava-option" "show-accounts-with-zero-transactions" "true"
2000-01-01 custom "fava-option" "show-accounts-with-zero-balance" "false"
2000-01-01 custom "fava-option" "show-metadata-indicators" "true"
2000-01-01 custom "fava-option" "collapse-pattern" "^Assets:Investments"
2000-01-01 custom "fava-option" "sidebar-show-queries" "5"
2000-01-01 custom "fava-option" "auto-reload" "false"
2000-01-01 custom "fava-option" "use-external-editor" "false"
2000-01-01 custom "fava-option" "invert-income-liabilities-equity" "false"
2000-01-01 custom "fava-option" "invert-gains-losses-colors" "false"
2000-01-01 custom "fava-option" "conversion-currencies" "USD EUR"
2000-01-01 custom "fava-option" "account-journal-include-children" "true"
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​

In stock Fava, open its Help → Options page for the installed release's reference and check Errors after changing a directive. The official 1.30.16 option help explains the settings.

In the Beancount.io dashboard, open a ledger's Settings page. Its Fava Options table shows the subset returned by the backend. This UI was verified in the product source snapshot, not through an authenticated production session. A displayed field does not imply the hosted dashboard implements stock Fava's editor, imports or URL routes.

See Also​

• Options Configuration — Beancount's core option directives.
• UI Features — Stock Fava workflows and hosted compatibility.