Your Interactive Brokers portfolio, kept current in self-hosted Ghostfolio.
Preview imports. Add new activities. Review corrections or enable a bounded profile.

Quick start · What it does · Safety · Configuration · Troubleshooting · Releases

What it does

Import IBKR trades, dividends, withholding tax and base-currency cash into self-hosted Ghostfolio. Run once or on a Docker schedule. Use one Ghostfolio target per IBKR account.

Key features

• Preview imports before you enable writes.
• Check identities, duplicates and holdings.
• Run on amd64 or arm64. Receive optional Apprise notifications.
• Review qualified one-to-one corrections, or enable a bounded reconciliation profile.

Deliberate boundaries

Options and FX trades are excluded. Handle corporate actions and older history manually. Unsafe BUY/SELL stay blocked. See limitations.

How it works

Read Flex reports and Ghostfolio activities. Map securities and check imports. Simulation shows the proposed result. Live mode imports activities and updates cash separately. A cash update does not prove that all activities were imported.

Quick start

Follow First installation:

1. Configure IBKR, Ghostfolio and mapping.
2. Set the network and persistent state.
3. Run simulation and review the result.
4. Back up Ghostfolio. Enable imports, then scheduling.

You need Docker Compose, Git, Ghostfolio 2.248.0+, IBKR Flex credentials, a Ghostfolio Security Token and a valid IANA TZ. Use one Flex query per account.

compose.yaml runs one account. For two accounts, use compose.multi-account.yaml. Existing two-service installs must switch files before updating. Follow the migration steps. Keep the project name, ENV and state paths. Do not remove orphans without review.

Docker image

Use ghcr.io/flowcool/ghostfolio-ibkr-sync:latest for the stable image. Pin @sha256:... for controlled upgrades. RC tags use vX.Y.Z-rc.N. They never replace :latest.

Startup reports ghostfolio-ibkr-sync version X.Y.Z — commit <12-character SHA>. The build sets this metadata. An RC can report the target version before release. See GitHub Releases.

Safety first

• Back up before the first import and significant upgrades. Image rollback does not undo writes.
• DRY_RUN defaults to simulation. Writes need an explicit false value and valid TZ. Account, currency, mapping and evidence checks still apply.
• Simulation reads services and maintains local evidence. It sends no financial writes.
• Keep CORPORATE_ACTION_STATE_FILE in a private persistent directory. Initialize it in simulation. Review the inventory before live mode. Missing state, bad permissions or active holds can cause exit 1 in simulation.
• Imports never delete activities. Corrections need exact-image qualification and explicit yes.
• Follow recovery after an uncertain write. Do not resend or delete state to clear a hold.
• Keep logs and tokens private. Keep credentials outside Git. Use docker compose config --quiet to avoid printing secrets.

For blocked trades, read corporate-action safety. For corrections, read activity review.

Configuration

• IBKR Flex fields
• Authentication and ENV
• Mapping
• Troubleshooting
• 3.0 upgrade and rollback
• 2.2 upgrade and rollback
• Maintenance · Older cleanup links

Essential settings

Use .env.example for Compose. See the ENV reference for all settings. Standalone Docker uses a separate ENV file.

Operational results

Cycle result reports success, required action or failure. Configured notifications repeat required actions after each completed run, including simulation. Clean success sends no heartbeat.

Check imports, cash, holds and delivery separately. sent confirms transport success, not device receipt. See required actions, delivery and cycle results.

Corporate-action safety

Include Corporate Actions in Flex, even when empty. The guide covers holds, state loss and evidence retention. Ordinary reports rotate after 30 days. Required safety evidence stays retained. Report windows cannot prove lifetime history. Manual acknowledgment cannot release a hold.

Official effective-date evidence

Follow the dated-evidence procedure. A date supplies evidence. It does not approve a financial write.

Native splits, notifications and recovery

See native evidence and recovery. Native split evidence needs qualified Ghostfolio 3.91.0+. This does not authorize split writes or historical conversion.

Limitations

• Flex covers at most 365 days. Reports update daily. Add older positions before newer sells need them.
• No options, FX trades or automatic corporate-action treatment.
• Account currencies must match. Cash is not converted.
• Holdings checks use net quantities, not chronological balances. A successful buy can remain after a later failure.
• No concurrent runs against one target account.
• Yahoo prices and metadata can be delayed or incomplete.

Read the full limits before recovery.

Releases and project status

GitHub Releases contains release history and artifacts. Changelog links there too.

Development and contribution

See Contributing for development, architecture and releases. Docker is the supported runtime. Local development requires Python 3.14+ with the pinned packages (CI and the container use Python 3.14).

Credits and license

Forked from obol89/ghostfolio-ibkr-sync. See LICENSE for the MIT NON-AI License and restrictions.