{"id":13595641,"url":"https://github.com/niklasf/python-chess","last_synced_at":"2025-05-14T08:02:10.085Z","repository":{"id":4898296,"uuid":"6054289","full_name":"niklasf/python-chess","owner":"niklasf","description":"A chess library for Python, with move generation and validation, PGN parsing and writing, Polyglot opening book reading, Gaviota tablebase probing, Syzygy tablebase probing, and UCI/XBoard engine communication","archived":false,"fork":false,"pushed_at":"2025-04-06T12:02:35.000Z","size":12944,"stargazers_count":2570,"open_issues_count":32,"forks_count":540,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-05-07T07:18:14.879Z","etag":null,"topics":["chess","epd","fen","gaviota","pgn","polyglot","syzygy","uci","xboard"],"latest_commit_sha":null,"homepage":"https://python-chess.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"cloudfoundry-samples/grails-petclinic","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niklasf.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG-OLD.rst","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"niklasf"}},"created_at":"2012-10-03T01:55:50.000Z","updated_at":"2025-05-06T07:00:58.000Z","dependencies_parsed_at":"2024-02-24T20:29:00.976Z","dependency_job_id":"35681b3c-d99e-4190-bf3a-0b9a0d43b857","html_url":"https://github.com/niklasf/python-chess","commit_stats":{"total_commits":3713,"total_committers":70,"mean_commits":"53.042857142857144","dds":0.4330729868031241,"last_synced_commit":"615a21b4ca7679c51388159324f2a9545868f6f1"},"previous_names":[],"tags_count":116,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklasf%2Fpython-chess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklasf%2Fpython-chess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklasf%2Fpython-chess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklasf%2Fpython-chess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niklasf","download_url":"https://codeload.github.com/niklasf/python-chess/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101581,"owners_count":22014905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","epd","fen","gaviota","pgn","polyglot","syzygy","uci","xboard"],"created_at":"2024-08-01T16:01:54.241Z","updated_at":"2025-05-14T08:02:06.365Z","avatar_url":"https://github.com/niklasf.png","language":"Python","funding_links":["https://github.com/sponsors/niklasf"],"categories":["Python","Projects"],"sub_categories":[],"readme":"python-chess: a chess library for Python\n========================================\n\n.. image:: https://github.com/niklasf/python-chess/workflows/Test/badge.svg\n    :target: https://github.com/niklasf/python-chess/actions\n    :alt: Test status\n\n.. image:: https://badge.fury.io/py/chess.svg\n    :target: https://pypi.python.org/pypi/chess\n    :alt: PyPI package\n\n.. image:: https://readthedocs.org/projects/python-chess/badge/?version=latest\n    :target: https://python-chess.readthedocs.io/en/latest/\n    :alt: Docs\n\n.. image:: https://badges.gitter.im/python-chess/community.svg\n    :target: https://gitter.im/python-chess/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\n    :alt: Chat on Gitter\n\nIntroduction\n------------\n\npython-chess is a chess library for Python, with move generation,\nmove validation, and support for common formats. This is the Scholar's mate in\npython-chess:\n\n.. code:: python\n\n    \u003e\u003e\u003e import chess\n\n    \u003e\u003e\u003e board = chess.Board()\n\n    \u003e\u003e\u003e board.legal_moves  # doctest: +ELLIPSIS\n    \u003cLegalMoveGenerator at ... (Nh3, Nf3, Nc3, Na3, h3, g3, f3, e3, d3, c3, ...)\u003e\n    \u003e\u003e\u003e chess.Move.from_uci(\"a8a1\") in board.legal_moves\n    False\n\n    \u003e\u003e\u003e board.push_san(\"e4\")\n    Move.from_uci('e2e4')\n    \u003e\u003e\u003e board.push_san(\"e5\")\n    Move.from_uci('e7e5')\n    \u003e\u003e\u003e board.push_san(\"Qh5\")\n    Move.from_uci('d1h5')\n    \u003e\u003e\u003e board.push_san(\"Nc6\")\n    Move.from_uci('b8c6')\n    \u003e\u003e\u003e board.push_san(\"Bc4\")\n    Move.from_uci('f1c4')\n    \u003e\u003e\u003e board.push_san(\"Nf6\")\n    Move.from_uci('g8f6')\n    \u003e\u003e\u003e board.push_san(\"Qxf7\")\n    Move.from_uci('h5f7')\n\n    \u003e\u003e\u003e board.is_checkmate()\n    True\n\n    \u003e\u003e\u003e board\n    Board('r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4')\n\nInstalling\n----------\n\nRequires Python 3.8+. Download and install the latest release:\n\n::\n\n    pip install chess\n\n\n`Documentation \u003chttps://python-chess.readthedocs.io/en/latest/\u003e`__\n--------------------------------------------------------------------\n\n* `Core \u003chttps://python-chess.readthedocs.io/en/latest/core.html\u003e`_\n* `PGN parsing and writing \u003chttps://python-chess.readthedocs.io/en/latest/pgn.html\u003e`_\n* `Polyglot opening book reading \u003chttps://python-chess.readthedocs.io/en/latest/polyglot.html\u003e`_\n* `Gaviota endgame tablebase probing \u003chttps://python-chess.readthedocs.io/en/latest/gaviota.html\u003e`_\n* `Syzygy endgame tablebase probing \u003chttps://python-chess.readthedocs.io/en/latest/syzygy.html\u003e`_\n* `UCI/XBoard engine communication \u003chttps://python-chess.readthedocs.io/en/latest/engine.html\u003e`_\n* `Variants \u003chttps://python-chess.readthedocs.io/en/latest/variant.html\u003e`_\n* `Changelog \u003chttps://python-chess.readthedocs.io/en/latest/changelog.html\u003e`_\n\nFeatures\n--------\n\n* Includes mypy typings.\n\n* IPython/Jupyter Notebook integration.\n  `SVG rendering docs \u003chttps://python-chess.readthedocs.io/en/latest/svg.html\u003e`_.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board  # doctest: +SKIP\n\n  .. image:: https://backscattering.de/web-boardimage/board.png?fen=r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR\u0026lastmove=h5f7\u0026check=e8\n      :alt: r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR\n\n* Chess variants: Standard, Chess960, Suicide, Giveaway, Atomic,\n  King of the Hill, Racing Kings, Horde, Three-check, Crazyhouse.\n  `Variant docs \u003chttps://python-chess.readthedocs.io/en/latest/variant.html\u003e`_.\n\n* Make and unmake moves.\n\n  .. code:: python\n\n      \u003e\u003e\u003e Nf3 = chess.Move.from_uci(\"g1f3\")\n      \u003e\u003e\u003e board.push(Nf3)  # Make the move\n\n      \u003e\u003e\u003e board.pop()  # Unmake the last move\n      Move.from_uci('g1f3')\n\n* Show a simple ASCII board.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board = chess.Board(\"r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4\")\n      \u003e\u003e\u003e print(board)\n      r . b q k b . r\n      p p p p . Q p p\n      . . n . . n . .\n      . . . . p . . .\n      . . B . P . . .\n      . . . . . . . .\n      P P P P . P P P\n      R N B . K . N R\n\n* Detects checkmates, stalemates and draws by insufficient material.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board.is_stalemate()\n      False\n      \u003e\u003e\u003e board.is_insufficient_material()\n      False\n      \u003e\u003e\u003e board.outcome()\n      Outcome(termination=\u003cTermination.CHECKMATE: 1\u003e, winner=True)\n\n* Detects repetitions. Has a half-move clock.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board.can_claim_threefold_repetition()\n      False\n      \u003e\u003e\u003e board.halfmove_clock\n      0\n      \u003e\u003e\u003e board.can_claim_fifty_moves()\n      False\n      \u003e\u003e\u003e board.can_claim_draw()\n      False\n\n  With the new rules from July 2014, a game ends as a draw (even without a\n  claim) once a fivefold repetition occurs or if there are 75 moves without\n  a pawn push or capture. Other ways of ending a game take precedence.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board.is_fivefold_repetition()\n      False\n      \u003e\u003e\u003e board.is_seventyfive_moves()\n      False\n\n* Detects checks and attacks.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board.is_check()\n      True\n      \u003e\u003e\u003e board.is_attacked_by(chess.WHITE, chess.E8)\n      True\n\n      \u003e\u003e\u003e attackers = board.attackers(chess.WHITE, chess.F3)\n      \u003e\u003e\u003e attackers\n      SquareSet(0x0000_0000_0000_4040)\n      \u003e\u003e\u003e chess.G2 in attackers\n      True\n      \u003e\u003e\u003e print(attackers)\n      . . . . . . . .\n      . . . . . . . .\n      . . . . . . . .\n      . . . . . . . .\n      . . . . . . . .\n      . . . . . . . .\n      . . . . . . 1 .\n      . . . . . . 1 .\n\n* Parses and creates SAN representation of moves.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board = chess.Board()\n      \u003e\u003e\u003e board.san(chess.Move(chess.E2, chess.E4))\n      'e4'\n      \u003e\u003e\u003e board.parse_san('Nf3')\n      Move.from_uci('g1f3')\n      \u003e\u003e\u003e board.variation_san([chess.Move.from_uci(m) for m in [\"e2e4\", \"e7e5\", \"g1f3\"]])\n      '1. e4 e5 2. Nf3'\n\n* Parses and creates FENs, extended FENs and Shredder FENs.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board.fen()\n      'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'\n      \u003e\u003e\u003e board.shredder_fen()\n      'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w HAha - 0 1'\n      \u003e\u003e\u003e board = chess.Board(\"8/8/8/2k5/4K3/8/8/8 w - - 4 45\")\n      \u003e\u003e\u003e board.piece_at(chess.C5)\n      Piece.from_symbol('k')\n\n* Parses and creates EPDs.\n\n  .. code:: python\n\n      \u003e\u003e\u003e board = chess.Board()\n      \u003e\u003e\u003e board.epd(bm=board.parse_uci(\"d2d4\"))\n      'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - bm d4;'\n\n      \u003e\u003e\u003e ops = board.set_epd(\"1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - bm Qd1+; id \\\"BK.01\\\";\")\n      \u003e\u003e\u003e ops == {'bm': [chess.Move.from_uci('d6d1')], 'id': 'BK.01'}\n      True\n\n* Detects `absolute pins and their directions \u003chttps://python-chess.readthedocs.io/en/latest/core.html#chess.Board.pin\u003e`_.\n\n* Reads Polyglot opening books.\n  `Docs \u003chttps://python-chess.readthedocs.io/en/latest/polyglot.html\u003e`__.\n\n  .. code:: python\n\n      \u003e\u003e\u003e import chess.polyglot\n\n      \u003e\u003e\u003e book = chess.polyglot.open_reader(\"data/polyglot/performance.bin\")\n\n      \u003e\u003e\u003e board = chess.Board()\n      \u003e\u003e\u003e main_entry = book.find(board)\n      \u003e\u003e\u003e main_entry.move\n      Move.from_uci('e2e4')\n      \u003e\u003e\u003e main_entry.weight\n      1\n\n      \u003e\u003e\u003e book.close()\n\n* Reads and writes PGNs. Supports headers, comments, NAGs and a tree of\n  variations.\n  `Docs \u003chttps://python-chess.readthedocs.io/en/latest/pgn.html\u003e`__.\n\n  .. code:: python\n\n      \u003e\u003e\u003e import chess.pgn\n\n      \u003e\u003e\u003e with open(\"data/pgn/molinari-bordais-1979.pgn\") as pgn:\n      ...     first_game = chess.pgn.read_game(pgn)\n\n      \u003e\u003e\u003e first_game.headers[\"White\"]\n      'Molinari'\n      \u003e\u003e\u003e first_game.headers[\"Black\"]\n      'Bordais'\n\n      \u003e\u003e\u003e first_game.mainline()  # doctest: +ELLIPSIS\n      \u003cMainline at ... (1. e4 c5 2. c4 Nc6 3. Ne2 Nf6 4. Nbc3 Nb4 5. g3 Nd3#)\u003e\n\n      \u003e\u003e\u003e first_game.headers[\"Result\"]\n      '0-1'\n\n* Probe Gaviota endgame tablebases (DTM, WDL).\n  `Docs \u003chttps://python-chess.readthedocs.io/en/latest/gaviota.html\u003e`__.\n\n* Probe Syzygy endgame tablebases (DTZ, WDL).\n  `Docs \u003chttps://python-chess.readthedocs.io/en/latest/syzygy.html\u003e`__.\n\n  .. code:: python\n\n      \u003e\u003e\u003e import chess.syzygy\n\n      \u003e\u003e\u003e tablebase = chess.syzygy.open_tablebase(\"data/syzygy/regular\")\n\n      \u003e\u003e\u003e # Black to move is losing in 53 half moves (distance to zero) in this\n      \u003e\u003e\u003e # KNBvK endgame.\n      \u003e\u003e\u003e board = chess.Board(\"8/2K5/4B3/3N4/8/8/4k3/8 b - - 0 1\")\n      \u003e\u003e\u003e tablebase.probe_dtz(board)\n      -53\n\n      \u003e\u003e\u003e tablebase.close()\n\n* Communicate with UCI/XBoard engines. Based on ``asyncio``.\n  `Docs \u003chttps://python-chess.readthedocs.io/en/latest/engine.html\u003e`__.\n\n  .. code:: python\n\n      \u003e\u003e\u003e import chess.engine\n\n      \u003e\u003e\u003e engine = chess.engine.SimpleEngine.popen_uci(\"stockfish\")\n\n      \u003e\u003e\u003e board = chess.Board(\"1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - 0 1\")\n      \u003e\u003e\u003e limit = chess.engine.Limit(time=2.0)\n      \u003e\u003e\u003e engine.play(board, limit)  # doctest: +ELLIPSIS\n      \u003cPlayResult at ... (move=d6d1, ponder=c1d1, info={...}, draw_offered=False, resigned=False)\u003e\n\n      \u003e\u003e\u003e engine.quit()\n\nSelected projects\n-----------------\n\nIf you like, share interesting things you are using python-chess for, for example:\n\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/syzygy.png?raw=true       | https://syzygy-tables.info/                                                                  |\n|     :height: 64                                                                                      |                                                                                              |\n|     :width: 64                                                                                       |                                                                                              |\n|     :target: https://syzygy-tables.info/                                                             | A website to probe Syzygy endgame tablebases                                                 |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/maia.png?raw=true         | https://maiachess.com/                                                                       |\n|     :height: 64                                                                                      |                                                                                              |\n|     :width: 64                                                                                       |                                                                                              |\n|     :target: https://maiachess.com/                                                                  | A human-like neural network chess engine                                                     |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/clente-chess.png?raw=true | `clente/chess \u003chttps://github.com/clente/chess\u003e`_                                            |\n|     :height: 64                                                                                      |                                                                                              |\n|     :width: 64                                                                                       |                                                                                              |\n|     :target: https://github.com/clente/chess                                                         | Oppinionated wrapper to use python-chess from the R programming language                     |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/crazyara.png?raw=true     | https://crazyara.org/                                                                        |\n|     :height: 64                                                                                      |                                                                                              |\n|     :width: 64                                                                                       |                                                                                              |\n|     :target: https://crazyara.org/                                                                   | Deep learning for Crazyhouse                                                                 |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/jcchess.png?raw=true      | `http://johncheetham.com \u003chttp://johncheetham.com/projects/jcchess/\u003e`_                       |\n|     :height: 64                                                                                      |                                                                                              |\n|     :width: 64                                                                                       |                                                                                              |\n|     :target: http://johncheetham.com/projects/jcchess/                                               | A GUI to play against UCI chess engines                                                      |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/pettingzoo.png?raw=true   | `https://pettingzoo.farama.org \u003chttps://pettingzoo.farama.org/environments/classic/chess/\u003e`_ |\n|     :width: 64                                                                                       |                                                                                              |\n|     :height: 64                                                                                      |                                                                                              |\n|     :target: https://pettingzoo.farama.org/environments/classic/chess/                               | A multi-agent reinforcement learning environment                                             |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/cli-chess.png?raw=true    | `cli-chess \u003chttps://github.com/trevorbayless/cli-chess\u003e`_                                    |\n|     :width: 64                                                                                       |                                                                                              |\n|     :height: 64                                                                                      |                                                                                              |\n|     :target: https://github.com/trevorbayless/cli-chess                                              | A highly customizable way to play chess in your terminal                                     |\n+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+\n\n* extensions to build engines (search and evaluation) – https://github.com/Mk-Chan/python-chess-engine-extensions\n* a stand-alone chess computer based on DGT board – https://picochess.com/\n* a bridge between Lichess API and chess engines – https://github.com/lichess-bot-devs/lichess-bot\n* a command-line PGN annotator – https://github.com/rpdelaney/python-chess-annotator\n* an HTTP microservice to render board images – https://github.com/niklasf/web-boardimage\n* building a toy chess engine with alpha-beta pruning, piece-square tables, and move ordering – https://healeycodes.com/building-my-own-chess-engine/\n* a JIT compiled chess engine – https://github.com/SamRagusa/Batch-First\n* teaching Cognitive Science – `https://jupyter.brynmawr.edu \u003chttps://jupyter.brynmawr.edu/services/public/dblank/CS371%20Cognitive%20Science/2016-Fall/Programming%20a%20Chess%20Player.ipynb\u003e`_\n* an `Alexa skill to play blindfold chess \u003chttps://www.amazon.com/Laynr-blindfold-chess/dp/B0859QF8YL\u003e`_ – https://github.com/laynr/blindfold-chess\n* a chessboard widget for PySide2 – https://github.com/H-a-y-k/hichesslib\n* Django Rest Framework API for multiplayer chess – https://github.com/WorkShoft/capablanca-api\n* a `browser based PGN viewer \u003chttps://about.nmstoker.com/chess2.html\u003e`_ written in PyScript – https://github.com/nmstoker/ChessMatchViewer\n* an accessible chessboard that allows blind and visually impaired  players  to play chess against Stockfish – https://github.com/blindpandas/chessmart\n* a web-based chess vision exercise – https://github.com/3d12/rookognition\n\n\nPrior art\n---------\n\nThanks to the Stockfish authors and thanks to Sam Tannous for publishing his\napproach to `avoid rotated bitboards with direct lookup (PDF) \u003chttp://arxiv.org/pdf/0704.3773.pdf\u003e`_\nalongside his GPL2+ engine `Shatranj \u003chttps://github.com/stannous/shatranj\u003e`_.\nSome move generation ideas are taken from these sources.\n\nThanks to Ronald de Man for his\n`Syzygy endgame tablebases \u003chttps://github.com/syzygy1/tb\u003e`_.\nThe probing code in python-chess is very directly ported from his C probing code.\n\nThanks to `Kristian Glass \u003chttps://github.com/doismellburning\u003e`_ for\ntransferring the namespace ``chess`` on PyPI.\n\nLicense\n-------\n\npython-chess is licensed under the GPL 3 (or any later version at your option).\nCheck out ``LICENSE.txt`` for the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniklasf%2Fpython-chess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniklasf%2Fpython-chess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniklasf%2Fpython-chess/lists"}