Wealthfolio logo Wealthfolio
Download
Docs
Wealthfolio FAQ

Wealthfolio FAQ

Answers to the questions we see most often about imports, transfers, FX, performance metrics, self-hosting, and more.

Last updated

This FAQ is the front door. For deeper explanations, follow the links inside each answer to the concept docs and user guide.

Getting started

A local-first, open-source investment tracker. The core app is free, your data stays on your device, and Wealthfolio Connect is an optional paid service if you want automatic broker sync or end-to-end encrypted multi-device sync.

Desktop (macOS, Windows, Linux), iOS, and self-hosted web. Each platform runs its own local database. See the Self-Hosting guide for the server build.

Yes. The desktop and self-hosted core are free forever. Connect is a subscription for broker sync and device sync — everything else works without it.

For each existing position, add a TRANSFER_IN activity with the External flag checked — it seeds the lot at your current quantity and cost basis without recording a fictional buy. Add a single DEPOSIT for your cash balance. You can switch to full BUY/SELL tracking going forward. See Activity Types for both styles.

Data, privacy, and backup

Locally, in an SQLite database.
  • Windows: %APPDATA%\Wealthfolio
  • macOS: ~/Library/Application Support/com.teymz.wealthfolio/
  • Linux: ~/.local/share/com.teymz.wealthfolio/
  • Mobile (iOS): App sandbox storage, backed up to iCloud if enabled.
  • Self-hosted: Data volume mounted at /app/data inside the container.

With Connect, data is encrypted on-device before syncing — we never see your portfolio data.

Settings → Exports → choose the Full database (SQL) option. This is a complete snapshot you can restore later. CSV and JSON exports are also available for individual collections. See Export & Backup.

The simplest path: copy the data directory from the old machine (see paths above) to the same location on the new machine. Alternatively, export the full database SQL on the old machine and import it on the new one.

Yes, with Wealthfolio Connect. Sync is end-to-end encrypted on-device — we can't read your portfolio. See the Connect & Broker Sync guide.

No. The only external calls the app makes are to market-data providers (for prices) and the updater (to check for new versions). No analytics, no telemetry.

CSV import

UTF-8, with a header row, ISO dates, decimal points (not commas), and one activity per row. The mapping step in the importer lets you align your broker's column names to Wealthfolio's fields. See the CSV Import guide for the full reference.

Two common gotchas:
  • Missing symbol: every row needs a symbol. For pure cash flows (deposits, withdrawals, interest), use $CASH-<CCY> — e.g. $CASH-USD.
  • $ in price fields: strip currency symbols before import. $57.50 should be 57.50. Same for thousands separators (1,234.56 → 1234.56).

Full troubleshooting list: CSV Import → Troubleshooting.

Yes. Use the $CASH-<CCY> symbol (e.g. $CASH-EUR) on DEPOSIT, WITHDRAWAL, INTEREST, FEE, and TAX rows. The importer treats those as pure cash activities — no security lookup is needed.

The importer detects exact duplicates by date + symbol + quantity + price + amount and skips them. If you're re-importing with corrections, you'll see how many rows are new vs. duplicates in the preview before confirming.

Yes — Schwab, Fidelity, Vanguard, IBKR, Robinhood, Trading 212, Questrade, BofA, and Guideline are documented in the CSV Import guide. If your broker isn't listed and you'd like to contribute a recipe, open a PR on GitHub.

Activities, transfers, dividends, splits

Create a TRANSFER_OUT on the source account and a matching TRANSFER_IN on the destination account. For securities transfers, Wealthfolio preserves the original cost basis. See Activity Types — Transfers.

Same-day gotcha: if both activities are dated the same day, give the OUT an earlier timestamp than the IN. Otherwise the IN may be processed before the lot exists on the source side.

Use a TRANSFER_OUT on the source account with the External flag checked — Wealthfolio closes the lots via FIFO without realising a gain, since the asset moved to an untracked destination. If the destination is another Wealthfolio account, leave the External flag unchecked and pick the destination account — Wealthfolio will create the matching TRANSFER_IN and preserve the original cost basis.

Create a DIVIDEND activity with the DRIP subtype. Wealthfolio records both the dividend income and the resulting share purchase in one step. The CSV importer auto-detects DRIP rows in most broker formats. See Dividend subtypes.

Add a SPLIT activity on the split date with the ratio (e.g. 4-for-1). Wealthfolio adjusts both quantity and per-share cost.

Don't double-apply. If your broker CSV already reflects post-split quantities and your price feed (e.g. Yahoo) shows adjusted prices, you may not need a SPLIT activity at all. Add one only if your historical quantities are pre-split.

Partial support today:
  • Options: in the Add Activity form, pick Buy or Sell, then switch the asset toggle from Stock to Option to get the Call/Put, strike, and expiration fields plus a Position (Open / Close) toggle. Writing a call or put is Sell + asset Option + Open (the button reads "Sell to Open"). An Option Expiry adjustment subtype cleans up expired contracts, and the standard 100x multiplier is applied automatically. See Options (calls & puts).
  • Short stock and ETF positions: use Sell Short to open a signed short lot and Buy to Cover to close it. Plain sells never accidentally open a short.
  • Covered calls and complex options strategies: not first-class strategy objects yet, though the underlying option trades can be recorded.
  • Bonds: tracked as securities. Record coupon payments as INTEREST against the bond symbol; Wealthfolio attributes the income to that bond and includes it in the bond's income and total return. Dedicated coupon-specific UI and reporting are not yet available.
  • RSUs / free shares: use TRANSFER_IN with the External flag checked and the cost basis you want to record (typically the vest-date price for tax purposes).

The easy-to-miss step is the asset toggle: pick the trade type first, then switch it from Stock to Option to reveal the option contract fields. To sell/write a call or put:

  1. Activities → + Add Manually → Add Transaction, then pick the Sell type.
  2. Under Asset & Account, switch the asset toggle from Stock to Option. Choose Call or Put, then set the symbol, strike, and expiration.
  3. In the Trade section set Position to Open, then enter the number of Contracts and the Premium/Share (Wealthfolio applies the 100x multiplier for you — enter 1.25, not 125). The button reads Sell to Open.

Close it later with Buy + asset Option + Close (Buy to Close), or use the Option Expiry adjustment subtype if it expires worthless. Buying an option to open is the mirror: Buy + asset Option + Open. Full walkthrough: Options (calls & puts).

Use INTEREST with the Staking Reward subtype. Wealthfolio records both the income and the resulting token acquisition in one step.

Two patterns work:
  • Gross + tax: record the DIVIDEND at the gross amount and a separate TAX activity for the withholding.
  • Net: record the DIVIDEND at the net amount your broker actually deposited. You lose the gross/withholding breakdown but cash reconciles cleanly.

Yes, if you log the same fee twice. Pick one: either include the commission as the fee field on the BUY/SELL, or create a separate FEE activity — not both. See How fees work.

Symbols & market data

Symbols are provider-agnostic. Each asset stores a canonical ticker (e.g. RY, AAPL) plus an optional exchange MIC code (e.g. XTSE for Toronto). Wealthfolio's resolver translates that into whatever format each market-data provider expects — Yahoo wants RY.TO, Börse Frankfurt wants XETR:RY, OpenFIGI wants an ISIN, and so on.

When you add an asset, you can type either the bare ticker or the exchange-qualified form your provider uses (e.g. RY.TO) — Wealthfolio parses the suffix into a ticker + MIC pair. The Yahoo suffix table is the most common case and is documented in Market Data & FX.

Add the exchange to the symbol when creating the asset — either as a Yahoo suffix (IWDA.AS for Euronext Amsterdam) or a MIC code in the dedicated exchange field. Once the asset is created, edit its Exchange setting any time to switch.

If a specific provider needs a different format for that asset (e.g. one of your custom scrapers wants IWDA-AMS), add a per-provider override in the asset's Market Data tab.

Built-in providers today:
  • Yahoo Finance — equities, ETFs, crypto, FX, commodities. Default for most users.
  • Alpha Vantage, Finnhub, MarketData.app — additional equity coverage (BYO API key).
  • OpenFIGI — bond / ISIN lookup.
  • Börse Frankfurt — German exchange listings.
  • Metal Price API — precious metals spot prices.
  • US Treasury Calc — Treasury / CUSIP data.
  • Custom providers — point at any JSON, HTML, table, or CSV source. See Custom Market Data Providers.

Per asset you can set a preferred provider and, when a provider needs a non-standard symbol, a per-provider override. The resolver falls through providers based on capability, health, and rate-limit headroom.

Two paths:
  1. Try the other built-in providers (Alpha Vantage, Finnhub, OpenFIGI for bonds, Börse Frankfurt for DE-listed). Set the asset's preferred provider under Market Data.
  2. Build a custom market data provider pointed at any public JSON API, HTML page, HTML table, or CSV. No coding required.

Open the asset → Market Data tab → set a per-provider override. For example, the asset's canonical symbol is SHOP but your custom provider fetches it as SHOP-CA — record the override and Wealthfolio uses it whenever it queries that provider, leaving the canonical symbol untouched.

Yes. Open the asset → Edit → set the Currency field. The next quote update will use the currency you set. Note that quote unit currency (what the provider returns — e.g. GBp pence) can differ from the asset's currency (GBP); Wealthfolio normalizes minor units automatically.

Most common causes:
  1. The provider returned bad or stale data. Check the Health Center — it flags suspect quotes.
  2. The symbol delisted. Switch to manual quotes in the asset's settings.
  3. The provider is rate-limited or its circuit breaker tripped after repeated failures. Wait a few minutes; Wealthfolio falls back to the next capable provider when one is unhealthy.
  4. The provider expects a different symbol than the canonical one — add a per-provider override (see above).

No. Once an asset has zero quantity across all accounts and no recent activities, Wealthfolio stops scheduling quote refreshes for it. Historical quotes are retained.

Multi-currency & FX

Wealthfolio uses the FX rate on the trade date to convert each activity into your base currency. When the FX rate moves later, your unrealized gain/loss in base currency will move too — even if the security price didn't change. Worked example and the math: Market Data & FX.

No — the account currency is set at creation. Workaround: create a new account in the correct currency and use TRANSFER_IN to move the holdings over (cost basis is preserved).

Goals are currently denominated in your base currency. Multi-currency goals are on the roadmap.

Rates come from your configured market data provider. To override, go to Settings → Exchange Rates and enter a manual rate for any pair — Wealthfolio will use your rate instead of the fetched one for that date forward.

Performance metrics

  • Per-account %: money-weighted return (MWR) — captures the impact of your timing decisions.
  • Total portfolio %: time-weighted return (TWR) — strips out contributions/withdrawals so it's comparable to a benchmark.

The two can disagree, and that's not a bug. See Performance Metrics for the full breakdown.

Usually one of:
  • Tiny starting denominator. If your portfolio started at $100 and grew to $50,000, the % return is enormous. Common on long timeframes for recently-funded accounts.
  • Manually-quoted asset with a step change. Going from no price to a price creates a one-day jump.
  • Bad provider data. Yahoo occasionally returns spurious spikes; the Health Center flags these.

Two different lenses. The account % blends realized gains (sales + dividends + interest) with unrealized gains (current market value vs. cost basis). A single holding might be down, while realized income and other holdings carry the account into profit.

FIFO today, intentionally. It's the most defensible default for tax reporting in most jurisdictions and keeps lot accounting simple to reason about. LIFO and weighted-average cost are planned — additional cost-basis methods will be added in future versions. See Cost Basis & Lots.

The cost-basis accounting is FIFO. The average cost you see on a holding is just a display figure — the total cost basis of your open lots divided by the shares remaining. It is not a moving-average accounting method, and Wealthfolio doesn't keep a running moving-average price.

This matters when you sell: realized gains close the oldest lot first (FIFO), not at a moving-average price. So in jurisdictions that tax on a moving average — such as Austria's gleitender Durchschnittspreis — Wealthfolio's realized-gain figures will diverge from your tax calculation, and you'll need to reconcile manually.

Moving-average / weighted-average cost (WAC) is planned — additional cost-basis methods will be added in future versions. See Cost Basis & Lots.

Accounts & contribution limits

Settings → Accounts → edit the account → toggle Active off. Archived accounts keep their data but are hidden from the dashboard.

Mark the account type, then Wealthfolio sums all DEPOSIT activities for the period and compares against the contribution limit you set. Full walkthrough: Contribution Limits.

By design — transfers between your own accounts aren't new contributions. If a transfer should count (e.g. a rollover from an external account that isn't tracked in Wealthfolio), use a DEPOSIT instead.

Yes. Add the asset with kind Property, Vehicle, Collectible, Precious Metal, or Liability. The Purchase price field acts as cost basis. Update value manually as the asset appreciates or depreciates. See Manage Accounts.

There's no first-class "virtual account" yet. Two workarounds:
  • Build it as a custom security (a fund-of-funds symbol you update manually).
  • Use Account Groups in Settings to roll up performance and net worth across multiple real accounts without double-counting.

Self-hosting & Connect

You can self-host for free. Connect is optional and only needed if you want automatic broker sync via SnapTrade, or end-to-end encrypted device sync. Self-hosting + manual imports needs nothing else. See Self-Hosting.

In 3.4.0+, the Docker container runs as UID 1000 instead of root. If your existing data volume is root-owned, SQLite will fail to write.

Fix: stop the container, then:

sudo chown -R 1000:1000 /path/to/your/wealthfolio/data

Start it again. See the self-hosting troubleshooting section.

The release-check ping (looking for updates). It carries no portfolio data. To disable, toggle off Settings → General → Check for updates automaticallyinside the app.

Wealthfolio doesn't block private IP ranges for custom providers — if the host resolves and responds, the fetcher runs. If you're not getting through, the issue is usually downstream: DNS, container networking, the reverse proxy's ACLs, or TLS verification. Test the provider URL from the same shell or container Wealthfolio runs from to isolate.

Not natively, but the web interface works as a Progressive Web App. On iOS Safari, open your self-hosted URL and choose Add to Home Screen — you get app-like access. Full native iOS app for self-hosted instances is on the roadmap.

wealthfolio/wealthfolio on Docker Hub. Pin to a specific tag for production (wealthfolio/wealthfolio:3.4.0) — latest will follow new major versions.

Yes — supported on the self-hosted web edition. Sign in through any OpenID Connect provider (Keycloak, Authentik, PocketID, Authelia, …) alongside or instead of the simple password; a successful SSO login mints the same session. Enable it with the WF_OIDC_* variables and set an email/subject allowlist. See the OIDC configuration reference.

Addons & AI

The official discovery page is in flight. For now, browse the wealthfolio-addons topic on GitHub or ask in Discord.

Download the .zip file, then Settings → Add-ons → + and select the zip. Wealthfolio will prompt for the permissions the addon requests before enabling it.

Start with the Addon Development guide. You'll need Node.js and pnpm. The dev mode supports hot-reload.

You pick. Configure Ollama for fully-local inference (free, no data leaves your machine), or BYO API key for OpenAI, Anthropic, or any OpenAI-compatible endpoint. The assistant uses function-calling against your local database — it never sends raw rows to the model, only the result of explicit, typed queries. Full details: AI Assistant.

Troubleshooting

Wealthfolio is signed, but some AV vendors flag new releases until they re-scan. Common fixes:
  • SmartScreen: click More info → Run anyway.
  • Kaspersky / similar: add an exception for the installer.
  • Verify the download: compare the SHA-256 hash from releases on GitHub.

Usually a missing WebKit dependency. Install the recommended packages:
  • Ubuntu / Debian: sudo apt install libwebkit2gtk-4.1-0 libsoup-3.0-0
  • Fedora: sudo dnf install webkit2gtk4.1 libsoup3

If issues persist, run the AppImage from a terminal to see the error output and file an issue.

Check that the app can reach wealthfolio.app (the release feed). If you're behind a corporate proxy, set HTTPS_PROXY in your environment. Worst case, download the new version manually from GitHub releases.

  • Windows: %LOCALAPPDATA%\com.teymz.wealthfolio\logs
  • macOS: ~/Library/Logs/com.teymz.wealthfolio
  • Linux: ~/.local/share/com.teymz.wealthfolio/logs

Attach the relevant log when filing an issue.

Try in order:
  1. Update to the latest version.
  2. Restart the app.
  3. Check your internet connection.
  4. Trigger a manual refresh — hover over the total value on the home page and click Update Portfolio.
  5. Open the Health Center — it'll flag stale quotes or data inconsistencies.

Checklist:
  1. First row of the CSV is headers, not data.
  2. UTF-8 encoded, comma-separated, no smart quotes.
  3. Strip $, currency symbols, and thousands separators from numeric fields.
  4. Dates in ISO-8601 (2025-03-15) or a format the mapping step recognizes.
  5. Activity types and symbols mapped correctly in the preview step.
  6. For cash activities, the amount column is filled in.

Full reference: CSV Import.
API Reference Glossary