python-chess

1.11.2 · active · verified Thu Apr 09

python-chess is a comprehensive Python library designed for chess programming. It provides core functionalities like move generation, move validation, and support for common chess formats such as PGN, FEN, and EPD. Additionally, it offers features for Polyglot opening book probing, Gaviota and Syzygy endgame tablebase probing, and communication with UCI/XBoard chess engines. The library is actively maintained, with the current stable version being 1.11.2, released in February 2025.

Warnings

breaking Version 1.11.0 dropped support for Python 3.7. Users on older Python versions must upgrade or use an older `python-chess` version. This release also introduced significant changes to `chess.engine` internals and how subclasses of `chess.Board` handle state recording/restoration.
Fix: Upgrade Python to 3.8+ or pin `python-chess<1.11.0`. For `chess.engine` and `chess.Board` subclass changes, consult the v1.11.0 changelog for migration details.
breaking In version 1.5.0, `chess.pgn.Mainline.__reversed__()` changed from returning a list to a generator, and `chess.pgn.ReverseMainline` was removed. This can break code that expected a list or relied on the removed class.
Fix: Update code to handle `__reversed__()` as a generator and remove any dependencies on `chess.pgn.ReverseMainline`.
breaking Older versions removed `chess.pgn.scan_headers()` and `chess.pgn.scan_offsets()`, replacing them with `chess.pgn.read_headers()` and `chess.pgn.skip_game()` for similar functionality.
Fix: Migrate to `chess.pgn.read_headers()` and `chess.pgn.skip_game()` for PGN header scanning and skipping games.
gotcha The `chess.Board.parse_san()` method is designed to be permissive and accepts various syntactical deviations beyond strict SAN (Standard Algebraic Notation), including fully specified moves like 'e2e4', castling with zeros, and null moves. This might lead to unexpected parsing if strict SAN adherence is assumed.
Fix: Be aware of the relaxed parsing behavior of `parse_san()`. If strict SAN validation is required, consider implementing additional validation logic or parsing using a different method if available.
gotcha For chess variants (e.g., Crazyhouse, King of the Hill), the specific `Board` classes are located in the `chess.variant` submodule and must be imported from there.
Fix: Import variant board classes explicitly from `chess.variant`, e.g., `from chess.variant import CrazyhouseBoard`.

Install

pip install chess Install core library

Imports

Board
```
import chess
board = chess.Board()
```
The primary `Board` class is available directly under the `chess` module.
Move
```
import chess
move = chess.Move.from_uci('e2e4')
```
The `Move` class is accessed directly from the `chess` module.
Game
```
import chess.pgn
game = chess.pgn.Game()
```
PGN-related classes like `Game` are in the `chess.pgn` submodule.
CrazyhouseBoard
```
import chess.variant
board = chess.variant.CrazyhouseBoard()
```
Board classes for chess variants are located in the `chess.variant` submodule.

Quickstart

Initializes a standard chess board, makes a move, and checks the game status.

import chess

# Create a new board
board = chess.Board()
print("Initial board:\n" + str(board))

# Make a move
move = chess.Move.from_uci("e2e4")
board.push(move)
print("\nBoard after e4:\n" + str(board))

# Check if the game is over
if board.is_checkmate():
    print("\nCheckmate!")
elif board.is_stalemate():
    print("\nStalemate!")
else:
    print("\nGame continues.")

view raw JSON →