{"id":2295,"library":"stockfish","title":"Stockfish Python Wrapper","description":"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.","status":"active","version":"4.0.8","language":"en","source_language":"en","source_url":"https://github.com/py-stockfish/stockfish","tags":["chess","engine","stockfish","game","AI"],"install":[{"cmd":"pip install stockfish","lang":"bash","label":"Install Python wrapper"}],"dependencies":[{"reason":"This Python library is a wrapper and requires the actual Stockfish executable to be installed separately on your system. Download from the official Stockfish website.","package":"Stockfish chess engine binary","optional":false}],"imports":[{"symbol":"Stockfish","correct":"from stockfish import Stockfish"}],"quickstart":{"code":"import os\nfrom stockfish import Stockfish\n\n# IMPORTANT: Replace with the actual path to your Stockfish engine executable\n# You can download the Stockfish engine from: https://stockfishchess.org/download/\nSTOCKFISH_PATH = os.environ.get('STOCKFISH_EXECUTABLE_PATH', '/usr/local/bin/stockfish')\n\ntry:\n    # Initialize Stockfish with the path to its executable\n    # It's recommended to adjust 'threads' and 'hash' for performance\n    stockfish = Stockfish(path=STOCKFISH_PATH, depth=15, parameters={'Threads': 2, 'Hash': 2048})\n    \n    # Set a starting position (e.g., standard chess opening FEN)\n    initial_fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'\n    stockfish.set_fen_position(initial_fen)\n    print(f\"Current FEN: {stockfish.get_fen_position()}\")\n    print(f\"Board visual:\\n{stockfish.get_board_visual()}\")\n    \n    # Get the best move\n    best_move = stockfish.get_best_move()\n    print(f\"Best move: {best_move}\")\n    \n    # Make a move\n    stockfish.make_moves_from_current_position([best_move])\n    print(f\"New FEN after move {best_move}: {stockfish.get_fen_position()}\")\n    print(f\"Board visual after move:\\n{stockfish.get_board_visual()}\")\n    \n    # Get evaluation\n    evaluation = stockfish.get_evaluation()\n    print(f\"Evaluation: {evaluation}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure the Stockfish engine is installed and its path is correctly set.\")\n\nfinally:\n    # Explicitly quit the Stockfish engine process if necessary (though __del__ usually handles it)\n    if 'stockfish' in locals() and stockfish:\n        stockfish.send_quit_command()","lang":"python","description":"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."},"warnings":[{"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')`).","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"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).","message":"Providing 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Tuning 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.","severity":"gotcha","affected_versions":"Stockfish engine versions 15+"},{"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.","message":"The `__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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}