Install & Compatibility
Where this runs
tested against v1.11.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.194s · 20.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.168s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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()
✗ import chess
game = chess.Game()
PGN-related classes like `Game` are in the `chess.pgn` submodule.
CrazyhouseBoard
✓ import chess.variant
board = chess.variant.CrazyhouseBoard()
✗ import chess
board = chess.CrazyhouseBoard()
Board classes for chess variants are located in the `chess.variant` submodule.
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.")
Debug
Known issues
breakingVersion 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.fixUpgrade 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.
affects: >=1.11.0
breakingIn 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.fixUpdate code to handle `__reversed__()` as a generator and remove any dependencies on `chess.pgn.ReverseMainline`.
affects: >=1.5.0
breakingOlder 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.fixMigrate to `chess.pgn.read_headers()` and `chess.pgn.skip_game()` for PGN header scanning and skipping games.
affects: Before 1.x (exact version unclear, pre-1.0)
gotchaThe `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.fixBe 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.
affects: All versions
gotchaFor 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.fixImport variant board classes explicitly from `chess.variant`, e.g., `from chess.variant import CrazyhouseBoard`.
affects: All versions
Errors
Common errors & fixes
AttributeError: module 'chess' has no attribute 'Board'
This error most commonly occurs when your Python script file is named `chess.py`, causing the interpreter to import your script instead of the installed `python-chess` library. It can also happen due to incorrect import statements.
fixRename your Python script file to something other than `chess.py` (e.g., `my_chess_game.py`). Ensure you are using the correct import pattern: `import chess` followed by `board = chess.Board()`.
ModuleNotFoundError: No module named 'chess'
The `python-chess` library is either not installed in your Python environment, or the Python interpreter cannot locate it in its search path. This can also occur after upgrading if previous installations conflict.
fixInstall the library using pip: `pip install chess`. If you recently upgraded and are still seeing this, try forcing a reinstall: `pip install --force-reinstall chess`.
ModuleNotFoundError: No module named 'chess.uci'
The `chess.uci` module was deprecated and removed in newer versions of `python-chess`, replaced by the more modern `chess.engine` module for UCI/XBoard engine communication.
fixUpdate your code to import `chess.engine` instead of `chess.uci` and adapt to the `chess.engine` API, which provides the functionalities for interacting with chess engines.
ValueError: invalid FEN
This error typically arises when attempting to initialize a `chess.Board` object with a malformed or syntactically incorrect Forsyth-Edwards Notation (FEN) string.
fixEnsure the FEN string strictly adheres to the standard FEN format. For example, a valid starting position FEN is `rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1`. Always double-check the FEN string for typos or structural errors before passing it to `chess.Board()`.
ValueError: invalid SAN
This error occurs when `board.parse_san()` is called with a Standard Algebraic Notation (SAN) string that is syntactically invalid, ambiguous, or represents an illegal move in the current board position.
fixProvide a syntactically correct and unambiguous SAN string for a legal move in the current position. You can get a list of legal moves in SAN format from `board.legal_moves` and convert them to SAN using `board.san(move)` to understand expected formats.
Upgrade
Version history
1.11.2latest on PyPI · released Feb 25, 2025
Audit
Dependencies
chess-gaviotaoptionalRequired for Gaviota endgame tablebase probing.
chess-syzygyoptionalRequired for Syzygy endgame tablebase probing.
python-chess-engine-extensionsoptionalAn example extension for building chess engines with python-chess.