python-chess: a pure Python chess library¶
Introduction¶
python-chess is a pure Python chess library with move generation, move validation and support for common formats. This is the Scholar’s mate in python-chess:
>>> import chess
>>> board = chess.Board()
>>> board.legal_moves
<LegalMoveGenerator at ... (Nh3, Nf3, Nc3, Na3, h3, g3, f3, e3, d3, c3, ...)>
>>> chess.Move.from_uci("a8a1") in board.legal_moves
False
>>> 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
>>> board
Board('r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4')
Features¶
Supports Python 3.4+ and PyPy3.
IPython/Jupyter Notebook integration. SVG rendering docs.
>>> board
Chess 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 move Move.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 . b q k b . r p p p p . Q p p . . n . . n . . . . . . p . . . . . B . P . . . . . . . . . . . P P P P . P P P R N B . K . N R
Detects checkmates, stalemates and draws by insufficient material.
>>> board.is_stalemate() False >>> board.is_insufficient_material() False >>> board.is_game_over() True
Detects repetitions. Has a half-move clock.
>>> board.can_claim_threefold_repetition() False >>> board.halfmove_clock 0 >>> board.can_claim_fifty_moves() False >>> board.can_claim_draw() False
With 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() False
Detects checks and attacks.
>>> board.is_check() True >>> board.is_attacked_by(chess.WHITE, chess.E8) True >>> attackers = board.attackers(chess.WHITE, chess.F3) >>> attackers SquareSet(0x0000000000004040) >>> chess.G2 in attackers True >>> 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) for m in ["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'} True
Detects absolute pins and their directions.
Reads Polyglot opening books. Docs.
>>> import chess.polyglot >>> book = chess.polyglot.open_reader("data/polyglot/performance.bin") >>> board = chess.Board() >>> main_entry = book.find(board) >>> main_entry.move() Move.from_uci('e2e4') >>> main_entry.weight 1 >>> main_entry.learn 0 >>> book.close()
Reads and writes PGNs. Supports headers, comments, NAGs and a tree of variations. Docs.
>>> import chess.pgn >>> with open("data/pgn/molinari-bordais-1979.pgn") as pgn: ... first_game = chess.pgn.read_game(pgn) >>> first_game.headers["White"] 'Molinari' >>> first_game.headers["Black"] 'Bordais' >>> first_game.mainline() <Mainline at ... (1. e4 c5 2. c4 Nc6 3. Ne2 Nf6 4. Nbc3 Nb4 5. g3 Nd3#)> >>> first_game.headers["Result"] '0-1'
Probe Gaviota endgame tablebases (DTM, WDL). Docs.
Probe Syzygy endgame tablebases (DTZ, WDL). Docs.
>>> import chess.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 on
asyncio
. Docs.>>> import chess.engine >>> engine = chess.engine.SimpleEngine.popen_uci("stockfish") >>> engine.id.get("name") 'Stockfish 10 64 POPCNT' >>> 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) <PlayResult at ... (move=d6d1, ponder=c1d1, info={...}, draw_offered=False)> >>> engine.quit()
Selected use cases¶
If you like, let me know if you are creating something intresting with python-chess, for example:
- a stand-alone chess computer based on DGT board – http://www.picochess.org/
- a website to probe Syzygy endgame tablebases – https://syzygy-tables.info/
- a GUI to play against UCI chess engines – http://johncheetham.com/projects/jcchess/
- deep learning for Crazyhouse – https://github.com/QueensGambit/CrazyAra
- a command-line PGN annotator – https://github.com/rpdelaney/python-chess-annotator
- a bot to play chess on Telegram – https://github.com/cxjdavin/tgchessbot
- an HTTP microservice to render board images – https://github.com/niklasf/web-boardimage
- a bridge between Lichess API and chess engines – https://github.com/careless25/lichess-bot
- a JIT compiled chess engine – https://github.com/SamRagusa/Batch-First
Acknowledgements¶
Thanks to the Stockfish authors and thanks to Sam Tannous for publishing his approach to avoid rotated bitboards with direct lookup (PDF) alongside his GPL2+ engine Shatranj. Some move generation ideas are taken from these sources.
Thanks to Ronald de Man for his Syzygy endgame tablebases. The probing code in python-chess is very directly ported from his C probing code.
Thanks to Miguel A. Ballicora for his Gaviota tablebases. (I wish the generating code was free software.)
License¶
python-chess is licensed under the GPL 3 (or any later version at your option). Check out LICENSE.txt for the full text.
Contents¶
- Core
- PGN parsing and writing
- Polyglot opening book reading
- Gaviota endgame tablebase probing
- Syzygy endgame tablebase probing
- UCI/XBoard engine communication (experimental)
- UCI engine communication
- SVG rendering
- Variants
- Changelog for python-chess
- New in v0.25.1
- New in v0.25.0
- New in v0.24.2
- New in v0.24.1, v0.23.11
- New in v0.24.0
- New in v0.23.10
- New in v0.23.9
- New in v0.23.8
- New in v0.23.7
- New in v0.23.6
- New in v0.23.5
- New in v0.23.4
- New in v0.23.3
- New in v0.23.2
- New in v0.23.1
- New in v0.23.0
- New in v0.22.2
- New in v0.22.1
- New in v0.22.0
- New in v0.21.2
- New in v0.21.1
- New in v0.21.0
- New in v0.20.1
- New in v0.20.0
- New in v0.19.0
- New in v0.18.4
- New in v0.18.3
- New in v0.18.2
- New in v0.18.1
- New in v0.18.0
- New in v0.17.0
- New in v0.16.2
- New in v0.16.1
- New in v0.16.0
- New in v0.15.4
- New in v0.15.3
- New in v0.15.2
- New in v0.15.1
- New in v0.15.0
- New in v0.14.1
- New in v0.14.0
- New in v0.13.3
- New in v0.13.2
- New in v0.13.1
- New in v0.13.0
- New in v0.12.5
- New in v0.12.4
- New in v0.12.3
- New in v0.12.2
- New in v0.12.1
- New in v0.12.0
- New in v0.11.1
- New in v0.11.0
- New in v0.10.1
- New in v0.10.0
- New in v0.9.1
- New in v0.8.3
- New in v0.9.0
- New in v0.8.2
- New in v0.8.1
- New in v0.8.0
- New in v0.7.0
- New in v0.6.0
- New in v0.5.0
- New in v0.4.2
- New in v0.4.1
- New in v0.4.0
- New in v0.3.1
- New in v0.3.0
- New in v0.2.0
- New in v0.1.0
- New in v0.0.4
- Pre v0.0.4