To help you get started, we've collected the most common ways that chess is being used within popular public projects.

linrock / chess-puzzle-maker / test / integration / test_puzzle_generation.py View on Github

def test_bishop_fork(self):
        # source https://lichess.org/training/61079
        # source game https://lichess.org/1n12OmvV
        # 34. Rb7
        board = chess.Board(
            '6k1/R4p2/1r3npp/2N5/P1b2P2/6P1/3r2BP/4R1K1 w - - 0 34'
        )
        puzzle = Puzzle(board, board.parse_san('Rb7'))
        puzzle.generate(depth=15)
        self.assertTrue(puzzle.is_complete())
        self.assertFalse(puzzle.player_moves_first)
        self.assertEqual(puzzle.category(), "Material")
        expected_uci_moves = ['a7b7', 'd2g2', 'g1g2', 'c4d5', 'g2g1', 'd5b7']
        self.assertEqual(
            [str(p.initial_move) for p in puzzle.positions][:6],
            expected_uci_moves
        )
        game = chess.pgn.read_game(io.StringIO(puzzle.to_pgn()))
        self.assertEqual(
            [m.uci() for m in game.mainline_moves()][:6],
            expected_uci_moves

View more ways to use chess

python-chess: a chess library for Python

Introduction

python-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:

>>> import chess

>>> board = chess.Board()

>>> board.legal_moves

>>> 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')

Installing

Requires Python 3.8+. Download and install the latest release:

pip install chess

Documentation

• Core
• PGN parsing and writing
• Polyglot opening book reading
• Gaviota endgame tablebase probing
• Syzygy endgame tablebase probing
• UCI/XBoard engine communication
• Variants
• Changelog

Features

• Includes mypy typings.

• 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.outcome()
  Outcome(termination=, winner=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(0x0000_0000_0000_4040)
  >>> 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
  
  >>> 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()
  
  
  >>> 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")
  
  >>> 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)
  
  
  >>> engine.quit()
  

Selected projects

If you like, share interesting things you are using python-chess for, for example:

	https://syzygy-tables.info/ A website to probe Syzygy endgame tablebases
	https://maiachess.com/ A human-like neural network chess engine
	clente/chess Oppinionated wrapper to use python-chess from the R programming language
	https://crazyara.org/ Deep learning for Crazyhouse
	http://johncheetham.com A GUI to play against UCI chess engines
	https://pettingzoo.farama.org A multi-agent reinforcement learning environment
	cli-chess A highly customizable way to play chess in your terminal

• extensions to build engines (search and evaluation) –

• a stand-alone chess computer based on DGT board –

• a bridge between Lichess API and chess engines –

• a command-line PGN annotator –

• an HTTP microservice to render board images –

• building a toy chess engine with alpha-beta pruning, piece-square tables, and move ordering –

• a JIT compiled chess engine –

• teaching Cognitive Science – https://jupyter.brynmawr.edu

• an Alexa skill to play blindfold chess –

• a chessboard widget for PySide2 –

• Django Rest Framework API for multiplayer chess –

• a browser based PGN viewer written in PyScript –

• an accessible chessboard that allows blind and visually impaired players to play chess against Stockfish –

• a web-based chess vision exercise –

Prior art

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 Kristian Glass for transferring the namespace chess on PyPI.

License

python-chess is licensed under the GPL 3 (or any later version at your option). Check out LICENSE.txt for the full text.