Getting Started

Get the latest version of Chess Analyzer Pro directly from our releases page or build it from source.

Option A: Download Executable (Recommended)

The easiest way to get started is using our precompiled binaries.

For Windows Users

1. Download: Visit the Releases Page and download the latest Windows installer (e.g., ChessAnalyzerPro-Setup.exe).
2. Install: Run the downloaded .exe file and follow the setup wizard instructions.
3. Run: Launch the application from your Start Menu or Desktop shortcut.

[!NOTE]

• SmartScreen Warning: On first run, you may see a Windows SmartScreen warning. Click "More Info" → "Run Anyway" to proceed. This is normal for unsigned applications.
• Visual C++ Requirement: Windows users must install the Microsoft Visual C++ Redistributable for the Stockfish engine to work properly.

For macOS Users

1. Download: Visit the Releases Page and download the latest macOS disk image (e.g., ChessAnalyzerPro.dmg).
2. Install: Open the downloaded .dmg file and drag ChessAnalyzerPro.app into your Applications folder.
3. Run: Launch the application from your Applications folder.

[!WARNING] Gatekeeper Quarantine: macOS may block the app from opening because it is unsigned. If it fails to launch, open Terminal and run the following command to authorize it:

xattr -dr com.apple.quarantine /Applications/ChessAnalyzerPro.app

For Linux Users

1. Download: Visit the Releases Page and download the latest Linux AppImage (e.g., ChessAnalyzerPro-x86_64.AppImage).
2. Make Executable: Right-click the file, go to Properties -> Permissions, and check "Allow executing file as program" (or run chmod +x in terminal).
3. Run: Double-click the AppImage to launch it.

Configure Stockfish

For analysis to work, you need to link the Stockfish engine:

1. Download Stockfish from stockfishchess.org.
2. Extract the downloaded engine to a memorable location on your computer.
3. In the app, go to Settings > Chess Engine, click Browse, select the Stockfish executable file (stockfish.exe on Windows, or the stockfish binary on macOS), and click Save Engine Path.
4. Click Test Engine to verify the path is valid and functional.

Option B: Build from Source

For macOS/Linux users or developers who want the latest changes.

Prerequisites

• Python 3.10 or higher (Download)
• Git (Download)
• Stockfish (Download)

Windows Setup

# 1. Clone the repository
git clone https://github.com/imutkarsht/Chess_analyzer.git
cd Chess_analyzer

# 2. Create virtual environment
python -m venv venv

# 3. Activate virtual environment
.\venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run the application
python main.py

macOS / Linux Setup

# 1. Clone the repository
git clone https://github.com/imutkarsht/Chess_analyzer.git
cd Chess_analyzer

# 2. Create virtual environment
python3 -m venv venv

# 3. Activate virtual environment
source venv/bin/activate

# 4. Install dependencies
pip3 install -r requirements.txt

# 5. Run the application
python3 main.py

[!NOTE] Since the app is built with PyQt6, it works best on KDE-based Linux distributions. On GNOME, some graphical glitches may occur, but the app remains fully functional.

Alternative: Using uv (Faster Package Management)

uv is a faster alternative to pip for managing Python packages.

# Install uv
pip install uv

# Create virtual environment
uv venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (macOS/Linux)
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Run
python main.py

First Run Configuration

When you first launch Chess Analyzer Pro, follow these steps:

1. Configure Stockfish Engine (Required)

1. Click the Settings icon (gear) in the sidebar.
2. Under Chess Engine, click Browse.
3. Navigate to and select your Stockfish executable:
   • Windows: stockfish.exe
   • macOS/Linux: stockfish (no extension)
4. Click Save Engine Path.
5. Click Test Engine to verify the path is valid and functional.

2. Add API Keys (Optional)

For AI features and Lichess integration:

Groq API Key (for AI Game Summary):

1. Get an API key from the Groq Console.
2. Paste it in Settings > API Configuration > Groq API Key.
3. Click Save. (You can also configure the model ID in the settings tab, which defaults to llama-3.3-70b-versatile).

Lichess Token (for book moves, private games, and better rate limits):

1. Generate a token at lichess.org/account/oauth/token.
2. Select "Read games" scope.
3. Paste in Settings > API Configuration > Lichess API Token and click Save. Note: A Lichess token is now required to fetch book moves from the Lichess Opening Explorer.

3. Set Your Usernames (Optional)

For personalized statistics and quick game loading:

1. Go to Settings > Player Usernames.
2. Enter your Chess.com and/or Lichess usernames.
3. Click Save.

Load Your First Game

1. Click the Load Game button in the sidebar (or press Ctrl+O).
2. The unified loading dialog will open. Select your preferred source tab:
   • PGN File: Drag & drop or click browse to load a .pgn file.
   • PGN Text: Paste raw PGN text directly from your clipboard.
   • Chess.com: Enter your Chess.com username to fetch recent games, or paste a game URL.
   • Lichess: Enter your Lichess username to fetch recent games, or paste a game URL.
3. If multiple games are found, choose one from the list.
4. Double-click your choice or click the Load Game button at the bottom.
5. Click the Analyze Game button in the sidebar to start the analysis!

Verify Everything Works

After analysis completes, you should see:

• ✅ Move List with classification icons (green checkmarks, yellow/red markers)
• ✅ Evaluation Graph showing the game's momentum
• ✅ Stats Panel with accuracy percentage and move breakdown
• ✅ Board with arrows showing engine recommendations

If any of these are missing, check the Troubleshooting guide.

Next Steps

• 📖 Read the Usage Guide to master all features
• ⚙️ Explore Configuration for customization options
• 📊 Learn about How We Calculate Analysis
• 🏗️ Check Architecture to understand the codebase