rust-chess

rust-chess is a Python package that acts as a bridge between the chess crate and Python. It aims to provide a high-performance chess library that is largely compatible with python-chess syntax.

This repository provides:

• A Python package rust-chess created using Maturin.
• A type stub (rust_chess.pyi) providing hover documentation and examples in IDEs.
• A benchmark comparison against python-chess with tests/benchmark.py and tests/batchmark.py.

WARNING

This project is almost out of alpha/beta phase (pun intended). Maybe expect some breaking changes, refactoring, and new features.

Overview

Quick usage example:

import rust_chess as rc

board = rc.Board()  # Create a board
move = rc.Move.from_uci("e2e4")  # Create move from UCI

# Check if the move is legal for the current board
if board.is_legal_move(move):
    # Make a move on the current board
    # Disable the legality check since we already know the move is legal
    board.make_move(move, check_legality=False)

# Make move onto a new board
new_board = board.make_move_new(rc.Move("e7e5"))

# Get the FEN of the current board
print(board.get_fen())

# Generate the next move
move = board.generate_next_move()

# Create a list of all legal moves (exhausts the generator)
moves = list(board.generate_legal_moves())

# The generator saves state
assert move not in moves

# Reset the generator to be able to generate moves again
board.reset_move_generator()

# Generate legal captures
captures = list(board.generate_legal_captures())

Use IDE completion or read the generated stub (rust_chess.pyi) for detailed function signatures and documentation. Actual documentation coming soon (TM).

Features

Data Types and Constants

• Color: WHITE, BLACK, COLORS
• PieceType: PAWN, KNIGHT, BISHOP, ROOK, QUEEN, KING, PIECE_TYPES
• Piece: WHITE_PAWN ... BLACK_KING, COLORED_PIECES
• Square: A1 ... H8, SQUARES
• Bitboard: BB_EMPTY, BB_FULL, BB_FILE_A ... BB_FILE_H, BB_RANK_1 ... BB_RANK_8, BB_FILES, BB_RANKS
• Move: WHITE_QUEENSIDE_CASTLE, WHITE_KINGSIDE_CASTLE, BLACK_QUEENSIDE_CASTLE, BLACK_KINGSIDE_CASTLE
• PyRepetitionDetectionMode enum: .NONE, .PARTIAL, .FULL
  • Currently no difference between partial and full for now, but the plan is to have partial have a smaller history list
• CastleRights enum: .NO_RIGHTS, .QUEENSIDE, .KINGSIDE, .BOTH
• BoardStatus enum: .ONGOING, .FIVE_FOLD_REPETITION, .SEVENTY_FIVE_MOVES, .INSUFFICIENT_MATERIAL, .STALEMATE, .CHECKMATE
• Board: No constants.
• BoardBatch: No constants.

Basic Features Overview

• Create a Board from an optional FEN string with board = rc.Board().
• Get the FEN of a board by calling get_fen() on a board object.
• Iterate over every square using the rc.SQUARES constant or get an individual square by using the corresponding constant (ex. rc.E2).
• Create a Bitboard from an integer or square.
  • Supports bitwise operators, shift operators, popcnt, iteration, and conversion to and from a Square.
• Get many different bitboards for the current board including board.get_color_bitboard(rc.WHITE), board.get_piece_type_bitboard(rc.PAWN), board.get_checkers_bitboard(), and more.
• Create a move from a source and destination square, with an optional promotion piece type using move = rc.Move(rc.E2, rc.E4).
  • Can also create a move from a UCI string using move = rc.Move("e2e4") or move = rc.Move.from_uci("e2e4").
• Check if a move is legal with board.is_legal_move(move).
• Generate all legal moves or captures for a board by iterating over board.generate_legal_moves() and board.generate_legal_captures().
  • The generator remembers state; make sure to reset it with board.reset_move_generator() if you want to iterate over the moves again.
• Generate the next move for the generator with board.generate_next_move().
• Generate moves for a specific bitboard mask by setting it with board.set_move_generator_mask(mask_bitboard) and then calling board.generate_moves().
• Apply a move to a board with board.make_move(move, check_legality=[True]|False).
  • check_legality defaults to True (can disable if you already know the move is legal for an extra performance boost).
• Apply a move to a new board with new_board = board.make_move_new(move).
• Check what piece, piece type, or color is on a square with the corresponding get_piece_on, get_piece_type_on, and get_color_on functions.
• Get the BoardStatus enum of a board with board.get_status().
  • Can also call individual status check functions like board.is_checkmate(), board.is_insufficient_material(), board.is_fifty_moves(), and more.
• Create a BoardBatch to apply functions to multiple boards at once.

Installation

Requires Python 3.10+.

A pip package is available at: https://pypi.org/project/rust-chess

1. Set up a virtual environment:

python -m venv .venv
source .venv/bin/activate
# Or
uv venv
source .venv/bin/activate

2. Use the pip package:

pip install rust-chess
# Or
uv pip install rust-chess

Building From Source

1. Set up a virtual environment:

python -m venv .venv
source .venv/bin/activate
# Or
uv venv
source .venv/bin/activate

2. Clone the repository:

git clone https://github.com/nemeott/rust-chess.git
cd rust-chess

3. Build and install the Python package:

./scripts/build.sh
pip install target/wheels/rust_chess-0.4.3-cp313-cp313-linux_x86_64.whl
# Or
uv pip install target/wheels/rust_chess-0.4.3-cp313-cp313-linux_x86_64.whl

# Or build and install in current virtual environment
./scripts/develop.sh

Roadmap

• Color
  • Color constants
  • Comparison between colors and booleans
• PieceType
  • Piece type constants
  • Get internal index representation
  • Printing
    • Basic characters
    • Unicode characters
• Piece
  • Piece constants
  • Get internal piece type index representation
  • Printing
    • Basic characters
    • Unicode characters
• Square
  • Square constants
  • Square creation and parsing
  • Get the rank and file from a square
  • Create a square from rank, file, or vice versa
  • Get the color of a square
  • Get the index of square
  • Use a square as an index
  • Rich comparison operators
  • Flip a square vertically
  • Bitboard conversion
  • Get adjacent squares
  • Get square forward/backward depending on color
  • Printing
• Bitboard
  • File and rank constants
  • Creation from a square or integer
  • Bitboard operations
    • Between bitboards
    • Between a bitboard and integer
  • Count the number of bits
  • Flip vertically
  • Iterate over the squares in a bitboard
  • Printing
    • Flip printing direction by default?
• Move
  • Move creation from data types or UCI
  • Castling move constants
• MoveGenerator
  • Generate the next move, legal move, and legal capture
  • Generate moves, legal moves, and legal captures
  • Support lazily iterating over the generator
  • Set a retain generator mask (bitboard of squares the generator will generate for)
  • Set an exclude generator mask (bitboard of squares the generator will avoid)
  • Remove a move from the generator
  • Reset the generator
• CastleRights
  • Get castle rights (No rights, queenside, kingside, both)
  • Rich comparison operators
• BoardStatus
  • Game-ending conditions
    • Checkmate
    • Stalemate
    • Insufficient material
    • Fivefold repetition
  • Potential draw conditions
    • Threefold repetition
    • Fifty moves
  • Rich comparison operators
• Board
  • FEN parsing and printing
  • UCI parsing and printing
  • SAN parsing
  • Human readable display
    • Basic characters
    • Unicode characters
    • Unicode with colors (ANSI)
  • Get the color, piece type, and piece on a square
  • Get the king and en passant squares
  • Get castle rights
  • Check if move is zeroing or legal
  • Quick legality detection for psuedo-legal moves
  • Check if move is a capture or en passant or is castling
  • Make moves on the current or new board
  • Make null moves on new board
  • Get bitboards
    • Pinned pieces
    • Checking pieces
    • Color pieces
    • Piece type
    • Piece
    • All pieces
  • Zobrist hashing
  • Comparison operators (using Zobrist hash)
  • Board history
    • Repetition detection
• BoardBatch
  • Initialization
    • Create a batch of boards from a count
    • Create a batch of boards from a list of FEN strings.
    • Create a batch of boards from a list of boards.
  • FEN parsing and printing
  • UCI parsing and printing
  • SAN parsing
  • Human readable display
    • Basic characters
    • Unicode characters
    • Unicode with colors (ANSI)
  • Dynamic tiled display
    • Basic characters
    • Unicode characters
    • Unicode with colors (ANSI)
  • Get the color, piece type, and piece on a respective square
  • Get the king and en passant squares for each board
  • Get castle rights for each board
  • Check if a resepective move is zeroing or legal for each board
  • Quick legality detection for psuedo-legal moves
  • Check if a respective move is a capture or en passant or is castling for each board
  • Make moves on the current or new board batch
  • Make null moves on new board batch
  • Get bitboards for the batch
    • Pinned pieces
    • Checking pieces
    • Color pieces
    • Piece type
    • Piece
    • All pieces
  • Zobrist hashing for each board
  • Comparison operators (using Zobrist hash)
  • Board history
    • Repetition detection for each board
• Miscellaneous
  • Cache default board for faster initialization
  • Piece-Square Table support?
  • Undo moves? (would require storing lots more and would slow down the library)
  • PGN support (parsing and writing)
  • UCI protocol basics
  • Opening book support
  • Improved Python ergonomics (e.g., more Pythonic wrappers where appropriate)
  • Multi-threading
  • Python thread support?
  • Comprehensive test suite
    • Docstring tests
    • Benchmark comparision to python-chess
    • Benchmarking individual functions with Criterion
    • Other tests
  • Working GitHub action

Comparison with python-chess

python-chess generates moves in reverse order (H8, H7, ...)* rust-chess generates moves in normal order (A1, A2, ...).

Performance

scripts/benchmark.py was used as a comprehensive benchmark comparision between similar functions in rust-chess and python-chess. Benchmarked on my Chromebook (Intel i5-1135G7). scripts/batchmark.py was used for a comparison between using methods on batches of boards. python-chess doesn't have a batch board class so this is kind of an unfair comparison. However, board batches could be useful for analyzing multiple games at once. The results from rust-chess v0.4.2 are as follows:

Benchmark Results (n=100,000)

Benchmark Results (n=10,000), (batch_size=25)

Analysis

• Small/simple operations (e.g., some tiny getters, Python-exposed primitives) can be slightly slower because of Rust<->Python boundary costs.
• Complex and heavy operations are substantially faster in rust-chess:
  • Creating moves from UCI.
  • Board initialization.
  • FEN parsing and printing.
  • Getting piece bitboards.
  • Generating moves, legal moves, and legal captures.
  • Batch move generation (WIP).
  • San parsing.
  • Zobrist hashing.
  • Checking move legality and check.
  • Repetition detection.
  • Board status checks.

Notable Limitations

• Bridge overhead: Small functions and data types are slower due to the bridge overhead, however heavy computations are much faster.
• No board history yet: Undo/pop are not available currently. Make moves onto a new board and pass it into a function instead for now.
• Reliability: The library has not been widely tested yet. It has pretty detailed docstring tests but not every edge case is guaranteed to be covered.

License

MIT License.