Registry / ai-ml / stockfish

stockfish

JSON →
library5.2.0pypypi✓ verified 24d ago

The `stockfish` library provides a Python wrapper for the powerful open-source Stockfish chess engine, enabling easy integration into Python applications. It allows users to control the engine, set board positions, get best moves, and retrieve evaluations. Currently at version 4.0.8, the library is actively maintained with frequent patch releases, typically releasing multiple updates within a month when new features or fixes are introduced.

pip install stockfish
INSTALL
IMPORT
SIG · STOCKFISH
S
stockfish
ai-mlpythonv5.2.0
Install
1.5s avg
Import
62ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.066s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.5s · import 0.058s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Stockfish
from stockfish import Stockfish

This quickstart demonstrates how to initialize the `Stockfish` class, set a FEN position, retrieve the best move, make a move, and get the engine's evaluation. Remember to replace `STOCKFISH_EXECUTABLE_PATH` with the actual path to your downloaded Stockfish engine binary. It's recommended to manage the Stockfish executable's path via an environment variable for easier deployment.

import os from stockfish import Stockfish # IMPORTANT: Replace with the actual path to your Stockfish engine executable # You can download the Stockfish engine from: https://stockfishchess.org/download/ STOCKFISH_PATH = os.environ.get('STOCKFISH_EXECUTABLE_PATH', '/usr/local/bin/stockfish') try: # Initialize Stockfish with the path to its executable # It's recommended to adjust 'threads' and 'hash' for performance stockfish = Stockfish(path=STOCKFISH_PATH, depth=15, parameters={'Threads': 2, 'Hash': 2048}) # Set a starting position (e.g., standard chess opening FEN) initial_fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1' stockfish.set_fen_position(initial_fen) print(f"Current FEN: {stockfish.get_fen_position()}") print(f"Board visual:\n{stockfish.get_board_visual()}") # Get the best move best_move = stockfish.get_best_move() print(f"Best move: {best_move}") # Make a move stockfish.make_moves_from_current_position([best_move]) print(f"New FEN after move {best_move}: {stockfish.get_fen_position()}") print(f"Board visual after move:\n{stockfish.get_board_visual()}") # Get evaluation evaluation = stockfish.get_evaluation() print(f"Evaluation: {evaluation}") except Exception as e: print(f"An error occurred: {e}") print("Please ensure the Stockfish engine is installed and its path is correctly set.") finally: # Explicitly quit the Stockfish engine process if necessary (though __del__ usually handles it) if 'stockfish' in locals() and stockfish: stockfish.send_quit_command()
Debug
Known issues
breakingThe `stockfish` Python package is a wrapper; it *does not* include the Stockfish chess engine executable itself. You must download and install the Stockfish engine binary separately for your operating system.
fix
Download the appropriate Stockfish engine executable from the official Stockfish website (https://stockfishchess.org/download/) and provide its full path to the `Stockfish` class constructor (e.g., `Stockfish(path='/path/to/stockfish_engine')`).
affects: All versions
gotchaProviding invalid input, such as an incorrectly formatted or illegal FEN position that causes the underlying Stockfish process to crash, will result in a `StockfishException` being raised by the wrapper.
fix
Validate all FEN strings and move inputs before passing them to the `Stockfish` object. The `is_fen_valid()` method can help, though it has some known limitations (e.g., for checkmates/stalemates).
affects: All versions
gotchaTuning engine parameters like `Skill Level` or `Elo` to reduce Stockfish's playing strength can be inconsistent or ineffective across different Stockfish engine versions. Some users report that these parameters do not always work as expected.
fix
Experiment with different combinations of `Skill Level`, `depth`, and `MultiPV` parameters. For significantly weaker play, consider using a lower `depth` and increasing `MultiPV` to encourage the engine to explore more options, potentially picking weaker ones.
affects: Stockfish engine versions 15+
gotchaThe `__del__()` method of the `Stockfish` class, which is intended to send a 'quit' command to the engine, is not guaranteed to be called by Python when the object goes out of scope.
fix
If explicit control over the Stockfish engine's lifecycle is critical, call `stockfish.send_quit_command()` directly when you are finished using the engine instance to ensure the process is terminated cleanly.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'stockfish'
The `stockfish` Python package is not installed in the current Python environment.
fix
pip install stockfish
OSError: Stockfish engine not found at path: <some_path>
The Stockfish chess engine executable file is either not downloaded, not at the specified path, or the provided path is incorrect.
fix
Download the appropriate Stockfish engine executable for your operating system and provide its absolute path to the `Stockfish` constructor, e.g., `Stockfish(path="/path/to/stockfish_executable")`.
ValueError: Provided FEN string is invalid
The FEN (Forsyth-Edwards Notation) string passed to `set_fen_position` does not adhere to the standard FEN format or represents an illegal chess position.
fix
Ensure the FEN string is correctly formatted according to the standard and represents a valid chess board state.
ValueError: Skill level must be between 0 and 20.
The `set_skill_level` method was called with an integer value that is outside the permitted range of 0 to 20.
fix
Call `set_skill_level()` with an integer argument between 0 and 20 (inclusive).
Upgrade
Version history
5.2.0latest on PyPI · released Apr 17, 2026
Audit
Dependencies
Stockfish chess engine binaryrequiredThis Python library is a wrapper and requires the actual Stockfish executable to be installed separately on your system. Download from the official Stockfish website.
Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
1
Resources
stockfish — pip install stockfish · libregistry