Skip to content

Quick Start

A 10‑minute guide to getting compare-my-stocks running with your first graph.

Already installed? Jump to First launch. \ Want to tune behavior? See CONFIGURATION.md.

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 the Start menu, or run compare-my-stocks.exe --console from a terminal if you want to see logs.

Option B — Developer (pip)

Requires Python 3.11.

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

After install, recommended to copy the bundled defaults to your data dir so you can edit them:

# Windows
xcopy /E /I "<site-packages>\compare_my_stocks\data" "$env:USERPROFILE\.compare_my_stocks\data"

# macOS / Linux
cp -r <site-packages>/compare_my_stocks/data ~/.compare_my_stocks/data

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

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. Sign in (read-only is fine).
  2. In TWS: Edit → Global Configuration → API → Settings
  3. Enable ActiveX and Socket Clients
  4. Note the Socket port (defaults: 7497 paper / 7496 live; gateway uses 4001/4002)
  5. Open ~/.compare_my_stocks/data/myconfig.yaml and set the port to match:
Sources: !SourcesConf
  IBSource: !IBSourceConf
    PortIB: 7497   # whatever TWS shows

Pictures: wiki page on TWS configuration.

2b. Polygon

  1. Sign up at https://polygon.io/ and create an API key.
  2. Edit myconfig.yaml:
Sources: !SourcesConf
  PolySource: !PolyConf
    Key: "YOUR_KEY_HERE"
Input: !InputConf
  InputSource: !InputSourceType Polygon

3. First launch

Developer:

python -m compare_my_stocks --console

End user (installed .exe):

compare-my-stocks.exe --console

--console keeps the terminal attached so you can see startup logs. Drop it once everything works.

On first run the app creates ~/.compare_my_stocks/, copies defaults, and opens the main window. If IB is configured it spawns the ibsrv sidecar in the background — that's normal.

You don't need transactions just to plot prices, but you do need them for P&L / portfolio features.

From My Stocks Portfolio (any broker)

  1. Export your portfolio CSV from the My Stocks Portfolio Android app.
  2. Drop it in the data dir as example_mystock.csv (or change SrcFile in config).

From Interactive Brokers (IB Flex)

  1. In IB Account Management, create a Flex Query for trades.
  2. Get your Flex Token.
  3. Add to myconfig.yaml:
TransactionHandlers: !TransactionHandlersConf
  IB: !IBConf
    FlexToken: "YOUR_TOKEN"
    FlexQuery: "YOUR_QUERY_ID"

From an IB Activity Statement (no Flex token)

If you can't or don't want to set up a Flex Query, you can seed your portfolio from a downloaded IB Activity Statement CSV. This source has no per-trade history — it only carries end-of-period state — but it is enough to plot current holdings P&L and to record realized P&L on closed positions.

  1. In IB Account Management → Reports → Activity, run an Activity Statement covering the period you care about and download it as CSV (the format that has section headers like Open Positions, Realized & Unrealized Performance Summary, and Statement).
  2. Save it into the data dir (default ~/.compare_my_stocks/) as ib_statement.csv, or change SrcFile in config.
  3. Enable the source in myconfig.yaml:
TransactionHandlers: !TransactionHandlersConf
  TransactionSource: !TransactionSourceType All        # IB | MyStock | IBStatement | All
  IBStatement: !IBStatementConf
    SrcFile: ib_statement.csv

What gets imported:

  • Open Positions (stocks only) → one synthetic buy per symbol at the statement's cost-price, dated at the statement's Period end.
  • Realized & Unrealized Performance Summary → for stocks that are fully closed (no open position), one synthetic sell with Qty=0 carrying the net long-term realized P&L.

Combining with IB Flex: if you use both, set IB.OnlyNewerThanIBStatement: true so IB Flex trades dated at or before the statement's WhenGenerated are dropped, and the statement acts as the historical baseline while Flex carries newer trades.

5. Make your first graph

  1. In the Symbol list, pick one or more tickers (e.g. AAPL, MSFT).
  2. In the Type dropdown, pick PRICE (or COMPARE to plot relative to a baseline like QQQ).
  3. Click Generate.

A line plot appears. From here you can:

  • Toggle Compare with to normalize against a benchmark.
  • Set a date range with the slider.
  • Define a Group (e.g. "Airlines") and unite by avg price/perf.
  • Save the graph parameters — they go into graphs.json.

Examples and more advanced flows are in the README and the wiki.

Troubleshooting

Problem Fix
App opens then nothing happens Run with --console to see logs.
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]"

Next steps

  • CONFIGURATION.md — every config option, what it does, the default.
  • README.md — feature tour and screenshots.
  • Wiki — extra guides and pitfalls.