Skip to content

Quick Start

A 10‑minute guide to getting compare-my-stocks running with live data.

Want to tune behavior? See CONFIGURATION.md. Looking for command-line flags? See CLI.md. Field guide to every control in the main window? See UI.md (and UI-INTRICACIES.md for runtime behaviour & pitfalls).

1. Install

Option A — End user (Windows installer)

  1. Grab the latest .exe installer from the Releases page.
  2. Run it. The default install location is fine.
  3. Launch from Start menu → Compare My Stocks → Compare My Stocks. The same folder also has (Console) (keeps the terminal attached so you can see logs), (Tutorial) (guided UI tour), Configure Compare My Stocks, and an uninstaller.

Option B — Developer (pip)

Requires Python 3.14.

On Windows, one PowerShell line — downloads the bundled installer to temp and runs it. The script handles both pip install and seeding the data dir:

$tmp="$env:TEMP\installdev.ps1"; irm https://raw.githubusercontent.com/eyalk11/compare-my-stocks/master/install/installdev.ps1 -OutFile $tmp; try { & $tmp } finally { rm $tmp -Force -ErrorAction SilentlyContinue }

Or, from a checkout:

./install/installdev.ps1                  # install from GitHub master
./install/installdev.ps1 -currentbranch   # install from this checkout
./install/installdev.ps1 -Branch dev      # install from a different branch

On macOS / Linux (or if you prefer to install by hand), the same two steps installdev.ps1 runs internally:

pip install "compare-my-stocks[full] @ git+https://github.com/eyalk11/compare-my-stocks.git@master"
python -c "import compare_my_stocks, os, shutil; src=os.path.join(os.path.dirname(compare_my_stocks.__file__),'data'); dst=os.path.join(os.path.expanduser('~'),'.compare_my_stocks'); shutil.copytree(src, dst, dirs_exist_ok=True); print('Copied',src,'->',dst)"

The data dir is ~/.compare_my_stocks/ by default. Override it with the COMPARE_STOCK_PATH environment variable.

You can already play with it. Before wiring up any credentials, launch Start menu → Compare My Stocks → Compare My Stocks (Tutorial) — it boots against frozen sample data and auto-starts the guided UI tour.

2. Pick a market data source

You need either Interactive Brokers or Polygon. IB is the default and gets you the most features (live portfolio sync). Polygon is easier if you just want price history.

2a. Interactive Brokers (default)

  1. Install and run Trader Workstation (TWS) or IB Gateway. Recommended: sign in with a read-only session — the app only needs to read prices and positions, so there's no reason to give it write access to your account.
  2. In TWS: Edit → Global Configuration → API → Settings
  3. Enable ActiveX and Socket Clients
  4. Tick Read-Only API (belt-and-braces on top of a read-only login).

TWS → Global Configuration → API → Settings: enable ActiveX and Socket Clients, and tick Read-Only API. Note the socket port — it must match PORTIB in myconfig.yaml.

More: wiki page on TWS configuration.

2b. Polygon

  1. Sign up at https://polygon.io/ and create an API key.
  2. Paste the key into the config GUI's RapidAPI / Polygon tab and set Input source to Polygon. The YAML equivalent is:
Sources: !SourcesConf
  PolySource: !PolyConf
    Key: "YOUR_KEY_HERE"
Input: !InputConf
  InputSource: !InputSourceType Polygon

Use the config editor. Instead of hand-editing YAML, launch the bundled config GUI — it has tabs for IB, Polygon, RapidAPI keys, the input source and behavior toggles, and a Help tab with screenshots showing how to obtain each token. Click the Config/Help… button in the app's main window, or run it standalone:

python -m compare_my_stocks.gui.config_gui

3. First launch

End user: open Start menu → Compare My Stocks and pick an entry:

  • Compare My Stocks — normal launch
  • Compare My Stocks (Console) — keep the terminal attached to see logs
  • Compare My Stocks (Tutorial) — guided UI tour on launch
  • Configure Compare My Stocks — standalone config GUI

Developer:

python -m compare_my_stocks --console

On first run the app creates ~/.compare_my_stocks/, copies defaults, and opens the main window. If IB is reachable and you don't yet have an Activity Statement, the app offers to seed a baseline straight from your live IB open positions — it asks once and remembers your answer (see § 4). You can trigger generation later from Config/Help… → Tutorial / Actions → Generate IB Statement now, or non-interactively via --generate-ib-statement (see CLI.md).

If something goes wrong, re-launch with --console to see startup logs in a terminal.

Tip — what's connected, what still needs configuring. A status bar along the bottom edge of the main window has all the information. It auto-hides, so move the mouse to the bottom of the window to bring it back.

4. With IB, or without?

How you use the app day-to-day depends on whether you run Interactive Brokers (TWS or IB Gateway) alongside it.

If you use IB (running alongside the app)

With TWS / IB Gateway running:

  • Market data — daily price history streams in automatically. Hit Refresh in the toolbar to pull new bars without restarting.
  • Recent trades on every launch — set up the Flex Web Service (token + query ID) once and recent trades pull in on every startup.
  • Portfolio sync — You can generate once an IB Activity Statement(automatically or download historical one) to seed the app with your positions, then fetch trades to bring postiions up to date. Value, Relaized P/L, and Unrealized P/L are all based on the portfolio as the app sees it.

If TWS isn't running, the app falls back to cached data; Refresh won't bring in anything new until IB is back.

If you don't use IB

You can still get most of the app — you just wire up the pieces by hand:

  • Prices — sign up at Polygon, paste the API key in Config/Help… → RapidAPI / Polygon, and set Input source to Polygon. Daily bars only; no forex.
  • Transactions — export your portfolio CSV from My Stocks Portfolio on Android and point Transactions → My Stocks Portfolio → Source file at it. Works with any broker. Re-export and re-point whenever you want recent trades reflected.
  • Splits (important!) — even on a Polygon-only setup, subscribe to yfinance-stock-market-data on RapidAPI and paste the key in RapidAPI / Polygon → Key (Jupyter). Without it, share counts go wrong after any stock split — and the app won't warn you. → config_help.md § 5.2

Refresh is manual: hit Refresh (or restart) to pull new Polygon bars; re-export your CSV when you want new trades.

For the deeper picture (cache TTLs, merging behavior, the OnlyNewerThanIBStatement cutoff, etc.) see DATA_SOURCES.md.

Helpers to configure

In addition to live market data, you would want fundamentals and split adjustments.

Helper What it unlocks
IB Activity Statement CSV Seeds historical positions + realized P&L from one export
IB Flex Web Service (token + query ID) Auto-pulls recent IB trades on every launch
My Stocks Portfolio CSV (Peeksoft Android app) Transactions from any broker, not just IB
yfinance via RapidAPI Split-adjusts your holdings + fundamentals + P/E and P/S charts
Seeking Alpha via RapidAPI (As an alternative to yfinance) P/E and P/S

All the helpers are optional, but the more you set up, the more the app can do for you. They are all easily configured via the GUI. Explore the tabs in Config/Help… for step-by-step instructions with screenshots.

What's next?

Field-by-field setup with screenshots lives in config_help.md (same content as the GUI's Help tab).

  • Have stock splits back-adjust your holdings — subscribe to yfinance-stock-market-data on RapidAPI and paste the key into RapidAPI / Polygon → Key (Jupyter). Without it, old share counts don't line up across splits. → config_help.md § 5.2
  • Have recent IB trades applied automatically — set up an IB Flex Web Service token + Activity Flex Query, paste them into Interactive Brokers → Flex token / Flex query ID. → config_help.md § 2
  • Seed historical positions from an IB statement — point Transactions → IB Activity Statement → Source file at the CSV exported from Client Portal → Statements → Activity Statement. → config_help.md § 1
  • Get P/E and P/S ratios on the chart — optional seeking-alpha RapidAPI key, or force the YFinance earnings backend to reuse the yfinance key above. → config_help.md § 5.3 · § 5.5
  • Use Polygon instead of IB for prices — paste the Polygon API key, switch Input source to Polygon. → config_help.md § 6

A detailed information about data sources, differences and choices — in DATA_SOURCES.md.

For a complete reference to configuration(too many options.. most better to leave as they are) , see CONFIGURATION.md.

Troubleshooting

Problem Fix
App opens then nothing happens
IB connection failed TWS not running, or PortIB doesn't match the socket port shown in TWS.
Wrong currency Check Symbols.Basecur, ExchangeCurrency, and StockCurrency in config.
Display looks tiny / huge Set Running.TryToScaleDisplay: false in config.
Errors at shutdown in --nogui Known, ignore — see CLAUDE.md.

Logs live in ~/.compare_my_stocks/log.txt and error.log.

Install profiles

Extra Use it for
[full] Everything (default for users)
[full_no_ib] Everything except ib_insync
[mini] Bare minimum runtime
[jupyter] Adds embedded Jupyter / Voila

Example:

pip install "compare-my-stocks[mini]"

References

  • UI.md — field guide to every control in the main window.
  • UI-INTRICACIES.md — runtime behaviour, the tri-state currency checkbox, refresh / auto-update queueing, and common pitfalls.
  • DATA_SOURCES.md — how IB / Polygon / Flex / Statement / CSV / RapidAPI fit together, merge behavior, caches, common gotchas.
  • config_help.md — field-by-field credential reference with screenshots.
  • CONFIGURATION.md — every config option, what it does, the default.
  • CLI.md — all command-line flags and environment variables.
  • README.md — feature tour and screenshots.
  • Wiki — extra guides and pitfalls.