Skip to main content
Help us improve Python packaging – donate today!

A pure Python chess library with move generation and validation and handling of common formats.

Project Description

https://travis-ci.org/niklasf/python-chess.svg?branch=v0.4.0 https://coveralls.io/repos/niklasf/python-chess/badge.png https://readthedocs.org/projects/python-chess/badge/?version=v0.4.0

Introduction

This is the scholars mate in python-chess:

>>> import chess

>>> board = chess.Bitboard()

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

Features

  • Supports Python 2.7 and Python 3.

  • Legal move generator and move validation. This includes all castling rules and en-passant captures.

    >>> chess.Move.from_uci("a8a1") in board.legal_moves
    False
    
  • Make and unmake moves.

    >>> Qf7 = board.pop() # Unmake last move (Qf7#)
    >>> Qf7
    Move.from_uci('h5f7')
    
    >>> board.push(Qf7) # Restore
    
  • Detects checkmates, stalemates and draws by insufficient material. Has a half-move clock.

    >>> board.is_stalemate()
    False
    >>> board.is_insufficient_material()
    False
    >>> board.is_game_over()
    True
    >>> board.halfmove_clock
    0
    
  • 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(0b100000001000000)
    >>> chess.G2 in attackers
    True
    
  • Parses and creates SAN representation of moves.

    >>> board = chess.Bitboard()
    >>> board.san(chess.Move(chess.E2, chess.E4))
    'e4'
    
  • Parses and creates FENs.

    >>> board.fen()
    'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
    >>> board = chess.Bitboard("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.Bitboard()
    >>> board.epd(bm=chess.Move.from_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
    
  • Read Polyglot opening books.

    >>> import chess.polyglot
    
    >>> book = chess.polyglot.open_reader("data/opening-books/performance.bin")
    >>> board = chess.Bitboard()
    >>> first_entry = next(book.get_entries_for_position(board))
    >>> first_entry.move()
    Move.from_uci('e2e4')
    >>> first_entry.learn
    0
    >>> first_entry.weight
    1
    
    >>> book.close()
    
  • Read and write PGNs. Supports headers, comments, NAGs and a tree of variations.

    >>> import chess.pgn
    
    >>> from __future__ import print_function # Python 2 compability for
    >>>                                       # this example.
    
    >>> pgn = open("data/games/molinari-bordais-1979.pgn")
    >>> first_game = chess.pgn.read_game(pgn)
    >>> pgn.close()
    
    >>> first_game.headers["White"]
    'Molinari'
    >>> first_game.headers["Black"]
    'Bordais'
    
    >>> # Iterate through the mainline of this embarrasingly short game.
    >>> node = first_game
    >>> while node.variations:
    ...     next_node = node.variation(0)
    ...     print(node.board().san(next_node.move))
    ...     node = next_node
    e4
    c5
    c4
    Nc6
    Ne2
    Nf6
    Nbc3
    Nb4
    g3
    Nd3#
    
    >>> first_game.headers["Result"]
    '0-1'
    

Peformance

python-chess is not intended to be used by serious chess engines where performance is critical. The goal is rather to create a simple and relatively highlevel library.

However, even though bit fiddling in Python is not as fast as in C or C++, the current version is still much faster than previous attempts including the naive x88 move generation from libchess.

Installing

  • With pip:

    sudo pip install python-chess
    
  • From current source code:

    python setup.py build
    sudo python setup.py install
    

License

python-chess is licensed under the GPL3. See the LICENSE file for the full copyright and license information.

Thanks to the developers of http://chessx.sourceforge.net/. Some of the core bitboard move generation parts are ported from there.

Release history Release notifications

History Node

0.23.1

History Node

0.23.0

History Node

0.22.2

History Node

0.22.1

History Node

0.22.0

History Node

0.21.2

History Node

0.21.1

History Node

0.21.0

History Node

0.20.1

History Node

0.20.0

History Node

0.19.0

History Node

0.18.4

History Node

0.18.3

History Node

0.18.2

History Node

0.18.1

History Node

0.18.0

History Node

0.17.0

History Node

0.16.2

History Node

0.16.1

History Node

0.16.0

History Node

0.15.4

History Node

0.15.3

History Node

0.15.2

History Node

0.15.1

History Node

0.15.0

History Node

0.14.1

History Node

0.14.0

History Node

0.13.3

History Node

0.13.2

History Node

0.13.1

History Node

0.13.0

History Node

0.12.5

History Node

0.12.4

History Node

0.12.3

History Node

0.12.2

History Node

0.12.1

History Node

0.12.0

History Node

0.11.1

History Node

0.11.0

History Node

0.10.1

History Node

0.10.0

History Node

0.9.1

History Node

0.9.0

History Node

0.8.3

History Node

0.8.2

History Node

0.8.1

History Node

0.8.0

History Node

0.7.0

History Node

0.6.0

History Node

0.5.0

History Node

0.4.2

History Node

0.4.1

This version
History Node

0.4.0

History Node

0.3.1

History Node

0.3.0

History Node

0.2.0

History Node

0.1.0

History Node

0.0.6

History Node

0.0.5

History Node

0.0.4

History Node

0.0.3

History Node

0.0.2

History Node

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python-chess-0.4.0.tar.gz (54.1 kB) Copy SHA256 hash SHA256 Source None Aug 19, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page