Package: chess
Introductionpython-chess is a chess library for Python, with move generation,
move validation, and support for common formats. This is the Scholar’s mate in
python-chess:>>>importchess>>>board=chess.Board()>>>board.legal_moves<LegalMoveGeneratorat...(Nh3,Nf3,Nc3,Na3,h3,g3,f3,e3,d3,c3,...)>>>>chess.Move.from_uci("a8a1")inboard.legal_movesFalse>>>board.push_san("e4")Move.from_uci('e2e4')>>>board.push_san("e5")Move.from_uci('e7e5')>>>board.push_san("Qh5")Move.from_uci('d1h5')>>>board.push_san("Nc6")Move.from_uci('b8c6')>>>board.push_san("Bc4")Move.from_uci('f1c4')>>>board.push_san("Nf6")Move.from_uci('g8f6')>>>board.push_san("Qxf7")Move.from_uci('h5f7')>>>board.is_checkmate()True>>>boardBoard('r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4')InstallingRequires Python 3.7+. Download and install the latest release:pip install chessDocumentationCorePGN parsing and writingPolyglot opening book readingGaviota endgame tablebase probingSyzygy endgame tablebase probingUCI/XBoard engine communicationVariantsChangelogFeaturesIncludes mypy typings.IPython/Jupyter Notebook integration.SVG rendering docs.>>>boardChess variants: Standard, Chess960, Suicide, Giveaway, Atomic,
King of the Hill, Racing Kings, Horde, Three-check, Crazyhouse.Variant docs.Make and unmake moves.>>>Nf3=chess.Move.from_uci("g1f3")>>>board.push(Nf3)# Make the move>>>board.pop()# Unmake the last moveMove.from_uci('g1f3')Show a simple ASCII board.>>>board=chess.Board("r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4")>>>print(board)r.bqkb.rpppp.Qpp..n..n......p.....B.P...........PPPP.PPPRNB.K.NRDetects checkmates, stalemates and draws by insufficient material.>>>board.is_stalemate()False>>>board.is_insufficient_material()False>>>board.outcome()Outcome(termination=<Termination.CHECKMATE:1>,winner=True)Detects repetitions. Has a half-move clock.>>>board.can_claim_threefold_repetition()False>>>board.halfmove_clock0>>>board.can_claim_fifty_moves()False>>>board.can_claim_draw()FalseWith the new rules from July 2014, a game ends as a draw (even without a
claim) once a fivefold repetition occurs or if there are 75 moves without
a pawn push or capture. Other ways of ending a game take precedence.>>>board.is_fivefold_repetition()False>>>board.is_seventyfive_moves()FalseDetects checks and attacks.>>>board.is_check()True>>>board.is_attacked_by(chess.WHITE,chess.E8)True>>>attackers=board.attackers(chess.WHITE,chess.F3)>>>attackersSquareSet(0x0000_0000_0000_4040)>>>chess.G2inattackersTrue>>>print(attackers)......................................................1.......1.Parses and creates SAN representation of moves.>>>board=chess.Board()>>>board.san(chess.Move(chess.E2,chess.E4))'e4'>>>board.parse_san('Nf3')Move.from_uci('g1f3')>>>board.variation_san([chess.Move.from_uci(m)formin["e2e4","e7e5","g1f3"]])'1. e4 e5 2. Nf3'Parses and creates FENs, extended FENs and Shredder FENs.>>>board.fen()'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'>>>board.shredder_fen()'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w HAha - 0 1'>>>board=chess.Board("8/8/8/2k5/4K3/8/8/8 w - - 4 45")>>>board.piece_at(chess.C5)Piece.from_symbol('k')Parses and creates EPDs.>>>board=chess.Board()>>>board.epd(bm=board.parse_uci("d2d4"))'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - bm d4;'>>>ops=board.set_epd("1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - bm Qd1+; id\"BK.01\";")>>>ops=={'bm':[chess.Move.from_uci('d6d1')],'id':'BK.01'}TrueDetectsabsolute pins and their directions.Reads Polyglot opening books.Docs.>>>importchess.polyglot>>>book=chess.polyglot.open_reader("data/polyglot/performance.bin")>>>board=chess.Board()>>>main_entry=book.find(board)>>>main_entry.moveMove.from_uci('e2e4')>>>main_entry.weight1>>>book.close()Reads and writes PGNs. Supports headers, comments, NAGs and a tree of
variations.Docs.>>>importchess.pgn>>>withopen("data/pgn/molinari-bordais-1979.pgn")aspgn:...first_game=chess.pgn.read_game(pgn)>>>first_game.headers["White"]'Molinari'>>>first_game.headers["Black"]'Bordais'>>>first_game.mainline()<Mainlineat...(1.e4c52.c4Nc63.Ne2Nf64.Nbc3Nb45.g3Nd3#)>>>>first_game.headers["Result"]'0-1'Probe Gaviota endgame tablebases (DTM, WDL).Docs.Probe Syzygy endgame tablebases (DTZ, WDL).Docs.>>>importchess.syzygy>>>tablebase=chess.syzygy.open_tablebase("data/syzygy/regular")>>># Black to move is losing in 53 half moves (distance to zero) in this>>># KNBvK endgame.>>>board=chess.Board("8/2K5/4B3/3N4/8/8/4k3/8 b - - 0 1")>>>tablebase.probe_dtz(board)-53>>>tablebase.close()Communicate with UCI/XBoard engines. Based onasyncio.Docs.>>>importchess.engine>>>engine=chess.engine.SimpleEngine.popen_uci("stockfish")>>>board=chess.Board("1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - 0 1")>>>limit=chess.engine.Limit(time=2.0)>>>engine.play(board,limit)<PlayResultat...(move=d6d1,ponder=c1d1,info={...},draw_offered=False,resigned=False)>>>>engine.quit()Selected projectsIf you like, share interesting things you are using python-chess for, for example:https://syzygy-tables.info/A website to probe Syzygy endgame tablebaseshttps://maiachess.com/A human-like neural network chess engineclente/chessOppinionated wrapper to use python-chess from the R programming languagehttps://crazyara.org/Deep learning for Crazyhousehttp://johncheetham.comA GUI to play against UCI chess engineshttps://pettingzoo.farama.orgA multi-agent reinforcement learning environmentcli-chessA highly customizable way to play chess in your terminalextensions to build engines (search and evaluation) –https://github.com/Mk-Chan/python-chess-engine-extensionsa stand-alone chess computer based on DGT board –http://www.picochess.org/a bridge between Lichess API and chess engines –https://github.com/careless25/lichess-bota command-line PGN annotator –https://github.com/rpdelaney/python-chess-annotatoran HTTP microservice to render board images –https://github.com/niklasf/web-boardimagebuilding a toy chess engine with alpha-beta pruning, piece-square tables, and move ordering –https://healeycodes.com/building-my-own-chess-engine/a JIT compiled chess engine –https://github.com/SamRagusa/Batch-Firstteaching Cognitive Science –https://jupyter.brynmawr.eduanAlexa skill to play blindfold chess–https://github.com/laynr/blindfold-chessa chessboard widget for PySide2 –https://github.com/H-a-y-k/hichesslibDjango Rest Framework API for multiplayer chess –https://github.com/WorkShoft/capablanca-apiabrowser based PGN viewerwritten in PyScript –https://github.com/nmstoker/ChessMatchVieweran accessible chessboard that allows blind and visually impaired  players  to play chess against Stockfish –https://github.com/blindpandas/chessmartAcknowledgementsThanks to the Stockfish authors and thanks to Sam Tannous for publishing his
approach toavoid rotated bitboards with direct lookup (PDF)alongside his GPL2+ engineShatranj.
Some move generation ideas are taken from these sources.Thanks to Ronald de Man for hisSyzygy endgame tablebases.
The probing code in python-chess is very directly ported from his C probing code.Thanks toKristian Glassfor
transferring the namespacechesson PyPI.Licensepython-chess is licensed under the GPL 3 (or any later version at your option).
Check out LICENSE.txt for the full text.