{"id":2241,"library":"chess","title":"python-chess","description":"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.","status":"active","version":"1.11.2","language":"python","source_language":"en","source_url":"https://github.com/niklasf/python-chess","tags":["chess","board game","pgn","fen","uci","xboard","engine","game development"],"install":[{"cmd":"pip install chess","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Required for Gaviota endgame tablebase probing.","package":"chess-gaviota","optional":true},{"reason":"Required for Syzygy endgame tablebase probing.","package":"chess-syzygy","optional":true},{"reason":"An example extension for building chess engines with python-chess.","package":"python-chess-engine-extensions","optional":true}],"imports":[{"note":"The primary `Board` class is available directly under the `chess` module.","symbol":"Board","correct":"import chess\nboard = chess.Board()"},{"note":"The `Move` class is accessed directly from the `chess` module.","symbol":"Move","correct":"import chess\nmove = chess.Move.from_uci('e2e4')"},{"note":"PGN-related classes like `Game` are in the `chess.pgn` submodule.","wrong":"import chess\ngame = chess.Game()","symbol":"Game","correct":"import chess.pgn\ngame = chess.pgn.Game()"},{"note":"Board classes for chess variants are located in the `chess.variant` submodule.","wrong":"import chess\nboard = chess.CrazyhouseBoard()","symbol":"CrazyhouseBoard","correct":"import chess.variant\nboard = chess.variant.CrazyhouseBoard()"}],"quickstart":{"code":"import chess\n\n# Create a new board\nboard = chess.Board()\nprint(\"Initial board:\\n\" + str(board))\n\n# Make a move\nmove = chess.Move.from_uci(\"e2e4\")\nboard.push(move)\nprint(\"\\nBoard after e4:\\n\" + str(board))\n\n# Check if the game is over\nif board.is_checkmate():\n    print(\"\\nCheckmate!\")\nelif board.is_stalemate():\n    print(\"\\nStalemate!\")\nelse:\n    print(\"\\nGame continues.\")","lang":"python","description":"Initializes a standard chess board, makes a move, and checks the game status."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.11.0"},{"fix":"Update code to handle `__reversed__()` as a generator and remove any dependencies on `chess.pgn.ReverseMainline`.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Migrate to `chess.pgn.read_headers()` and `chess.pgn.skip_game()` for PGN header scanning and skipping games.","message":"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.","severity":"breaking","affected_versions":"Before 1.x (exact version unclear, pre-1.0)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Import variant board classes explicitly from `chess.variant`, e.g., `from chess.variant import CrazyhouseBoard`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.11.2':69 '2025':73 'activ':61 'addit':37 'board':75 'book':44 'chess':3,6,14,29,56,74 'common':28 'communic':53 'comprehens':9 'core':18 'current':65 'design':12 'develop':83 'endgam':49 'engin':57,81 'epd':36 'featur':40 'februari':72 'fen':34,78 'format':30 'function':19 'game':76,82 'gaviota':46 'generat':22 'librari':11,59 'like':20 'maintain':62 'move':21,23 'offer':39 'open':43 'pgn':33,77 'polyglot':42 'probe':45,51 'program':15 'provid':17 'python':2,5,10 'python-chess':1,4 'releas':70 'stabl':66 'support':26 'syzygi':48 'tablebas':50 'uci':79 'uci/xboard':55 'valid':24 'version':67 'xboard':80","created_at":"2026-04-09T18:49:33.247022+00:00","updated_at":"2026-04-16T02:00:53.053558+00:00","problems":[{"fix":"Rename 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()`.","cause":"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.","error":"AttributeError: module 'chess' has no attribute 'Board'"},{"fix":"Install 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`.","cause":"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.","error":"ModuleNotFoundError: No module named 'chess'"},{"fix":"Update 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.","cause":"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.","error":"ModuleNotFoundError: No module named 'chess.uci'"},{"fix":"Ensure 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()`.","cause":"This error typically arises when attempting to initialize a `chess.Board` object with a malformed or syntactically incorrect Forsyth-Edwards Notation (FEN) string.","error":"ValueError: invalid FEN"},{"fix":"Provide 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.","cause":"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.","error":"ValueError: invalid SAN"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.11.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/niklasf/python-chess","docs":"https://python-chess.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/chess/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":[],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}