Python chess client

chess-board, chess-engine, chess-game, game, player, python, python-2, python-library, python3
pip install chess_py==3.3.1




Build Status Code Climate PyPI version Python27 Python35 License Twitter


chess_py is available under the MIT license. See the LICENSE file for more info. Copyright © 2016 Aubhro Sengupta. All rights reserved.

Talk @Pygotham 2016

I gave a talk at PyGotham 2016 on this library. Abstract can be found here.


Chess_py is an open source chess library written in Python designed to aid in the creation of chess engines. Handles the chess so you can focus on the engine.


To use as a immediately start up a game between two human players in the console, navigate inside the root directory of the package and run


To install package

pip (Recommended)

pip install chess_py

Or manually

python install


View complete technical documentation here.

Great! How do you use it? (An Example)

Chess_py has the capability of creating games between players, either human, or AI

import chess_py
from chess_py import Game, Human, color

""" Creates a Game with 2 humans. 
When run, this will open the console,"""
new_game = Game(Human(color.white), Human(

""" After game is completed, outcome will be stored in result.
The integer result will be one of three values. 
white wins - 0, black wins - 1, draw - 0.5 """
result =

To build a chess engine on with chess_py, inherit Player and implement generate_move()

import chess_py
from chess_py import Game, Human, color

# Engine which plays the move with the highest immediate material advantage
class MyEngine(chess_py.Player):
    def __init__(self, input_color):
      # Creates piece value scheme to specify value of each piece.
      self.piece_values = chess_py.PieceValues.init_manual(PAWN_VALUE=1,
      # Super call to
      super(chess_py.Player, self).__init__(input_color)
    def generate_move(self, position):
      # position parameter is an object of type Board
      # Finds all possible moves I can play.
      moves = position.all_possible_moves(self.color)
      # Initalizes best move and advantage after it has been played to dummy values.
      best_move = None
      best_move_advantage = -99
      # Loops through possible moves
      for move in moves:
        """ advantage_as_result(move, piece_values) finds numerical advantage
        as specified by piece value scheme above. Returns negative values for
        positions of disadvantage. Returns +/-99 for checkmate. """
        advantage = position.advantage_as_result(move, self.piece_values)
        # If this move is better than best move, it is the best move.
        if advantage >= best_move_advantage:
            best_move = move
            best_move_advantage = advantage
      return best_move

# If file is run as script, a Game is set up between My_engine and Human and result is printed.
if __name__ == "__main__":
    new_game = Game(MyEngine(color.white), Human(
    # white wins - 0, black wins - 1, draw - 0.5 
    print("Result: ",