SC2 Replay Analyzer

Analyze your StarCraft II replays with filtering, stats, and beautiful terminal output.

Features

Auto-detect SC2 replay folders on Mac, Windows, and Linux
Parse replays and extract worker counts, army value, APM, MMR, and more
Interactive filtering - dynamically filter by matchup, result, length, workers
Auto-completion - tab-complete commands with usage hints
Win/loss streaks - find patterns in your games
Win/loss statistics with averages and matchup breakdowns
SQLite caching - parse each replay only once
Streaming overlays - OBS-compatible MMR graph overlay for Twitch/YouTube

Installation

pip install sc2-replay-analyzer

Quick Start

# First run - auto-detects your replay folder and player name
sc2

# Scan for new replays
sc2 scan

# Interactive filtering mode
sc2 live

# Show statistics
sc2 stats

Commands

Command	Description
`sc2`	First run: setup wizard. After: auto-scan + interactive mode
`sc2 scan`	Scan replay folder for new games
`sc2 live`	Interactive filtering mode
`sc2 stats`	Show aggregate statistics
`sc2 config`	Re-run setup / change player name
`sc2 show`	Show games with filters
`sc2 export`	Export to CSV
`sc2 latest`	Show detailed stats for most recent game

Interactive Mode

The sc2 live command opens an interactive filtering mode with tab-completion:

SC2 Replay Analyzer - Interactive Mode
Type commands to filter. 'help' for options, 'q' to quit. Tab for completion.

> -m TvZ          # Filter by matchup
> -r W            # Show only wins
> -l >10:00       # Games longer than 10 minutes
> -w <40          # Games with <40 workers at 8min
> -s win:3+       # Find 3+ win streaks
> +p 1            # Add 1 previous game (cumulative)
> clear           # Reset all filters
> q               # Quit

Filter Commands

Command	Description	Example
`-n, --limit`	Limit results to N games	`-n 50`
`-m, --matchup`	Filter by matchup (TvZ, TvP, etc)	`-m TvZ`
`-r, --result`	Filter by result (W/L)	`-r W`
`-l, --length`	Filter by game length	`-l >8:00`
`-w, --workers`	Filter by workers @8m	`-w <40`
`-d, --days`	Games from last N days	`-d 7`
`-s, --streaks`	Find win/loss streaks	`-s win:3+`
`--map`	Filter by map name	`--map Alcyone`
`+p, --prev`	Add N previous games (cumulative)	`+p 1`
`+n, --next`	Add N next games (cumulative)	`+n 2`
`columns`	Manage display columns
`clear`	Reset all filters
`help`	Show help
`q`	Quit

Column Commands

Command	Description	Example
`columns`	List available columns
`columns add <col>`	Add column(s) to display	`columns add bases_6m`
`columns remove <col>`	Remove column(s)	`columns remove mmr`
`columns reset`	Reset to default columns

Configuration

Config is stored in ~/.sc2analyzer/config.toml:

player_name = "YourName"
replay_folder = "~/Library/Application Support/Blizzard/StarCraft II/Accounts/.../Replays/Multiplayer"

[benchmarks]
workers_6m = 40
workers_8m = 55

[display]
columns = ["date", "map", "matchup", "result", "mmr", "apm", "workers_8m", "army", "length"]

Available Columns

apm, army, bases_10m, bases_6m, bases_8m, date, length, map, matchup, mmr, opponent, opponent_apm, opponent_mmr, result, worker_kills, worker_losses, workers_10m, workers_6m, workers_8m

Streaming Overlay (OBS)

Display your MMR progression as a live overlay on your stream.

Installation

pip install sc2-replay-analyzer[server]

Usage

Run sc2 or sc2 live (overlay server starts automatically)
In OBS: Add Browser Source
URL: http://localhost:8337/overlays/mmr-graph
Size: 800 x 250

The overlay shows:

Your player name and current MMR
MMR change over last 100 games
Win rate percentage
Interactive graph with win/loss colored points

Configuration

Add to ~/.sc2analyzer/config.toml:

[server]
enabled = true  # Set to false to disable overlay server
port = 8337     # Change port if needed

Development

Updating README

After modifying commands, run:

python scripts/generate_readme.py

This updates the auto-generated sections marked with  comments.

Requirements

Python 3.8+
StarCraft II replays (.SC2Replay files)

License

MIT

Metadata

Release files for sc2-replay-analyzer 0.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sc2-replay-analyzer 0.20.0
File	Size	Uploaded
sc2_replay_analyzer-0.20.0.tar.gz	93.6 kB	Mar 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sc2-replay-analyzer 0.20.0
File	Interpreter	ABI	Platform	Reset
sc2_replay_analyzer-0.20.0-py3-none-any.whl 83.2 kB Mar 29, 2026	Python 3	none	any	Details

Total release size: 176.9 kB

Release files / sc2_replay_analyzer-0.20.0.tar.gz

Download URL	sc2_replay_analyzer-0.20.0.tar.gz
Size	93.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`2805de6cfbc4a68b17369d1088c9f4436a399f92de0f61f0dc47ddbdfddbf059`
BLAKE2b-256 checksum How to use checksums	`6f6a45ceb2c2bc9074e38d4fbb0e46bb9d72bc3820ebf7a850f8e53c2ceb9d58`
Upload date	Mar 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.14`

Release files / sc2_replay_analyzer-0.20.0-py3-none-any.whl

Download URL	sc2_replay_analyzer-0.20.0-py3-none-any.whl
Size	83.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9274420504080305ab6c89b48dc1e2b83cf54f29727fa66b5630ec0701cf68a9`
BLAKE2b-256 checksum How to use checksums	`0a3e07d57da934e1e2f16df6e7b542b43b74cc645ff43e4323db4b1801f42195`
Upload date	Mar 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.14`