Configuration¶

Paisa stores its configuration in paisa.yaml. You can edit it from the web interface or as a text file. Paisa looks for it in this order:

The path in the PAISA_CONFIG environment variable.
The path passed with --config.
The current working directory.
paisa/paisa.yaml inside the user's Documents folder.

If no file exists, Paisa creates paisa/paisa.yaml in Documents. The defaults use INR and en-IN; change the currency, locale, and financial-year start when they do not match your location.

Basic settings¶

These are the settings most people change first:

Setting	Purpose	Example
`default_currency`	Currency used for totals and conversions	`INR`
`locale`	Number and date formatting	`en-IN`
`financial_year_starting_month`	First month of the financial year	`4`
`ledger_cli`	Ledger engine used to read journals	`ledger`
`journal_path`	Main journal file	`/home/john/Documents/paisa/main.ledger`
`db_path`	SQLite database file	`/home/john/Documents/paisa/paisa.db`

The web interface can edit the same settings.

Account patterns¶

Several features accept a list of accounts. Use a full name such as Assets:Equity:APPLE, * to match descendants such as Assets:Equity:*, or negation such as !Expenses:Tax. Do not mix positive and negated patterns in the same list.

Budgets and goals¶

budget.rollover controls whether unused budget carries into the next month. The goals section defines retirement and savings goals, including their accounts, target, date, contribution, and expected return assumptions. See Budgets and Goals before changing these values.

Investments and tax¶

Use commodities for price providers and tax categories, allocation_targets for portfolio targets, and schedule_al for Schedule AL account groups. Related guides cover commodities and prices, allocation targets, and Schedule AL.

Import and prediction¶

import_templates stores reusable statement templates. Merchant-to-account rules live under prediction.merchant_rules and take precedence over general prediction history. See Import statements and Account suggestions for the workflow.

Authentication¶

user_accounts protects the web interface with usernames and passwords. The UI stores new or changed passwords as Argon2id hashes and upgrades legacy sha256: credentials after a successful login. See Authentication for the security boundaries and HTTPS requirements.

Credit cards¶

Each credit_cards entry connects statement dates, due dates, limits, and card details to an existing liability account. See Credit cards for an annotated example.

Complete example¶

The example below collects the available settings in one place. Copy only the sections you need and adjust their values for your journal.

# Path to your journal file. It can be absolute or relative to the
# configuration file. The main journal file can refer other files using
# `include` as long as all the files are in the same or sub directory
# REQUIRED
journal_path: /home/john/Documents/paisa/main.ledger

# Path to your database file. It can be absolute or relative to the
# configuration file. The database file will be created if it does not exist.
# REQUIRED
db_path: /home/john/Documents/paisa/paisa.db

# Path to your sheets directory. It can be absolute or relative to the
# configuration file. The sheets directory will be created if it does not exist.
# By default it will be created in the same directory as the journal file.
# OPTIONAL, DEFAULT: same directory as journal file.
sheets_directory: sheets

# The ledger client to use
# OPTIONAL, DEFAULT: ledger, ENUM: ledger, hledger, beancount
ledger_cli: ledger

# The default currency to use. NOTE: Paisa tries to convert other
# currencies to default currency, so make sure it's possible to
# convert to default currency by specifying the exchange rate.
#
# OPTIONAL, DEFAULT: INR
default_currency: INR

# The precision to show in UI. NOTE: This applies only to the UI, not
# to the entries in journal.
#
# OPTIONAL, DEFAULT: 0
display_precision: 0

# The column to align the amount in the editor.
#
# OPTIONAL, DEFAULT: 52
amount_alignment_column: 52

# The locale used to format numbers. The list of locales supported
# depends on your browser. It's known to work well with en-US and en-IN.
#
# OPTIONAL, DEFAULT: en-IN
locale: en-IN

# The time zone used to parse and format dates. If not set, system
# time zone will be used. Example values are Asia/Kolkata,
# America/New_York, etc
#
# OPTIONAL, DEFAULT: system timezone
time_zone: ""

# First month of the financial year. This can be set to 1 to follow
# January to December.
#
# OPTIONAL, DEFAULT: 4
financial_year_starting_month: 4

# First day of the week. This can be set to 1 to follow Monday to
# Sunday. 0 represents Sunday, 1 represents Monday and so on.
#
# OPTIONAL, DEFAULT: 0
week_starting_day: 0

# When strict mode is enabled, all the accounts and commodities should
# be defined before use. This is same as --pedantic flag in ledger and
# --strict flag in hledger. Doesn't apply to beancount.
#
# OPTIONAL, ENUM: yes, no DEFAULT: no
strict: "no"

## Budget
budget:
  # Rollover unspent money to next month
  # OPTIONAL, ENUM: yes, no DEFAULT: yes
  rollover: "yes"

## Goals
goals:
  # Retirement goals
  retirement:
    # Goal name
    # REQUIRED
    - name: Retirement
      # Goal icon
      # REQUIRED
      icon: mdi:palm-tree
      # Safe Withdrawal Rate
      # OPTIONAL, DEFAULT: 4
      swr: 2
      # List of expense accounts
      # OPTIONAL, DEFAULT: Expenses:*
      expenses:
        - Expenses:Clothing
        - Expenses:Education
        - Expenses:Entertainment
        - Expenses:Food
        - Expenses:Gift
        - Expenses:Insurance
        - Expenses:Misc
        - Expenses:Restaurant
        - Expenses:Shopping
        - Expenses:Utilities
      # List of accounts where you keep retirement savings
      # OPTIONAL, DEFAULT: Assets:*
      savings:
        - Assets:Equity:*
        - Assets:Debt:*
      # By default, average of last 3 year expenses will be used to
      # calculate your yearly expenses. This can be overridden by setting
      # this configuration to positive value
      # OPTIONAL, DEFAULT: 0
      yearly_expenses: 0
  savings:
    # Goal name
    # REQUIRED
    - name: House
      # Goal icon
      # REQUIRED
      icon: fluent-emoji-high-contrast:house-with-garden
      # Goal target amount
      # REQUIRED
      target: 100000
      # Goal target date
      # OPTIONAL (either target_date or payment_per_period can be specified)
      target_date: "2030-01-01"
      # Expected rate of returns
      # OPTIONAL
      payment_per_period: 0
      # Expected rate of returns
      # OPTIONAL, REQUIRED if target_date or payment_per_period is set
      rate: 5
      # List of accounts where you keep the goal's savings
      # REQUIRED
      accounts:
        - Assets:Equity:**
## Schedule AL
# OPTIONAL, DEFAULT: []
schedule_al:
  # Code
  # REQUIRED, ENUM: immovable, metal, art, vehicle, bank, share,
  # insurance, loan, cash, liability
  - code: metal
    accounts:
      - Assets:Gold
  - code: bank
    accounts:
      - Assets:Checking
      - Assets:Debt:Cash:FD
  - code: share
    accounts:
      - Assets:Equity:*
  - code: insurance
    accounts:
      - Assets:Debt:Insurance

## Allocation Target
# OPTIONAL, DEFAULT: []
allocation_targets:
  - name: Debt
    target: 30
    accounts:
      - Assets:Debt:*
      - Assets:Checking
  - name: Equity
    target: 60
    accounts:
      - Assets:Equity:*
  - name: Equity Foreign
    target: 20
    accounts:
      - Assets:Equity:NASDAQ
  - name: Equity Index
    target: 20
    accounts:
      - Assets:Equity:NIFTY
  - name: Equity Active
    target: 20
    accounts:
      - Assets:Equity:PPFAS
  - name: Others
    target: 10
    accounts:
      - Assets:Gold
      - Assets:RealEstate

## Commodities
# OPTIONAL, DEFAULT: []
commodities:
  - name: NASDAQ
    # Required, ENUM: mutualfund, stock, nps, unknown
    type: mutualfund
    price:
      # Required, ENUM: in-mfapi, com-yahoo, com-purifiedbytes-nps, co-alphavantage
      provider: in-mfapi
      # differs based on provider
      code: 145552
    harvest: 1095
    # Optional, ENUM: equity65, equity35, debt, unlisted_equity
    tax_category: debt
  - name: NIFTY
    type: mutualfund
    price:
      provider: in-mfapi
      code: 120716
    harvest: 365
    tax_category: equity65
  - name: APPLE
    type: stock
    price:
      provider: com-yahoo
      code: AAPL
    harvest: 1095
    tax_category: equity65

## Import Templates
# OPTIONAL, DEFAULT: []
import_templates:
  - name: SBI Account Statement
    # Required
    content: |
      {{#if (isDate ROW.A "D MMM YYYY")}}
        {{date ROW.A "D MMM YYYY"}} {{ROW.C}}
        {{#if (isBlank ROW.F)}}
          {{predictAccount prefix="Expenses"}}      {{amount ROW.E}} INR
          Assets:Checking:SBI
        {{else}}
          Assets:Checking:SBI                       {{amount ROW.F}} INR
          {{predictAccount prefix="Income"}}
        {{/if}}
      {{/if}}
    # Should be a valid handlebar template

## Prediction
# OPTIONAL, DEFAULT: empty merchant_rules
prediction:
  merchant_rules:
    # Grouped merchant list shorthand:
    - account: "Expenses:Groceries"
      merchants:
        - "supermarket central"
        - "fresh mart"
        - "corner grocery"
        - "quick commerce"

    - account: "Expenses:Groceries:Vegetables"
      merchants:
        - "green farm market"
        - "city produce"
        - "fresh vegetables"

    # Singular merchant rule (also supported for backward compatibility):
    - merchant: "swiggy instamart"
      account: "Expenses:Groceries"

    # Merchant text is matched after normalization. The import template prefix
    # still hard-filters the account, so an Expenses rule is ignored for
    # prefix="Income".

## Accounts: account customization
# OPTIONAL, DEFAULT: []
accounts:
  - name: Liabilities:CreditCard:IDFC
    # Required, name of the account
    icon: arcticons:idfc-first-bank
    # Optional, use the UI to select the icon.

## List of user accounts.
# If the list is empty, then no authentication will be performed.
# Remote/network-exposed Paisa instances should always be hosted behind HTTPS.
# Passwords in UI configuration are stored using Argon2id ($argon2id$...).
# Legacy sha256:... credentials remain fully backwards-compatible and are
# opportunistically upgraded to Argon2id upon successful authentication.
#
# OPTIONAL, DEFAULT: []
user_accounts:
  - username: john.doe
    # Required. When updated via the UI or API, password values are hashed with Argon2id.
    password: $argon2id$v=19$m=65536,t=3,p=2$c2FsdHNhbHRzYWx0c2FsdA$aGFzaGhhc2hoYXNoaGFzaGhhc2hoYXNoaGFzaGhhc2g

## List of credit cards
# OPTIONAL, DEFAULT: []
credit_cards:
  - account: Liabilities:CreditCard:Freedom
    # Required, account name
    credit_limit: 150000
    # Required, credit limit of the card
    statement_end_day: 8
    # Required, the day of the month when the statement is generated
    due_day: 20
    # Required, the day of the month when the payment is due
    network: visa
    # Required, the network of the card
    number: "0007"
    # Required, the last 4 digits of the card number
    expiration_date: "2029-05-01"
    # Required, the expiration date of the card