PicoChess

PicoChess is chess engine management software for Raspberry Pi, other Linux computers, Windows, and macOS; it is not itself a chess engine. Its distinctive strength is combining modern and retro chess engines with physical electronic chess boards. Retro chess computers can be emulated through MAME on Linux. Native Windows and macOS support is experimental and intended primarily for web-only play with native UCI engines. See the Windows and macOS installation guides for setup and current limitations.

PicoChess can also be used without an electronic board: play entirely from a web browser on a phone, tablet, or desktop. Raspberry Pi and Linux installations include Stockfish and Leela Chess Zero (LC0) as examples, and you can add other modern or retro engines, including classics such as Mephisto and TuroChamp. See the "How to add more engines" section below for details. Windows and macOS use their own native engine setup, described in the platform guides.

♟️ Support AI-assisted PicoChess development

Contributions help cover the AI service subscription costs used for PicoChess development and maintenance; they are not intended as payment for the maintainers' work hours. At present, these services cost approximately US$24 per month. Future use of automated development agents on GitHub may add further service costs. Companies interested in sponsoring these monthly costs are welcome to contact the maintainers through the PicoChess Google Group.

Contributing

New contributors are welcome—even if you are new to programming. Start with the beginner contribution guide, or open Picochess in a cloud workspace after forking it:

The AI-assisted contribution guide explains a safe path from a clear issue to a draft pull request without requiring a local IDE or Git expertise.

Features

• Play via Web Browser. Enjoy chess directly from your browser. You do not need an electronic chess board.
• Use phone browser audio as an alternative to local speakers. This is useful on headless systems such as DGT3000 clock setups or Pi systems without external speakers.
• Electronic Chess Board support for an authentic playing experience. Compatible with DGT e-board, Certabo, ChessLink, Chessnut, iChessOne, Novag Citrine, and Saitek OSA (Leonardo, Galileo, and Renaissance). Note that no guarantees can be given that it will work with all of these boards, but the community has worked hard to maintain this possibility. I currently use a DGT e-board and a DGT Pi 3000 myself.
• DGT Clock Compatibility. Runs on the DGT Pi 3000 electronic clock which becomes an all-in one chess computer.
• Responsive web layout scales well on large desktop screens.

Select Novag Citrine or Saitek OSA in the E-Board Type menu, or set board-type = citrine or board-type = osa in picochess.ini. The current Saitek OSA driver uses the board's internal firmware to display moves on all three models.

About This Fork

This fork of Picochess focuses on:

• Upgrading dependencies – Uses the latest Python with the latest chess and Tornado libraries.
• Runs on Raspberry Pi and other Linux computers, with experimental native Windows and macOS support.
• Asynchronous Architecture – Replaces threads with an async-based architecture for improved performance and scalability.
• Keep the main program picochess.py as it was, rewrites are mainly focusing on engine.py and picotutor.py to use the latest python chess library, but as the new library is quite different some changes are visible in picochess.py as well.
• Wayland support with native audio backend for web/desktop installs (no X11/PulseAudio requirement).
• Engines, books, and games database are distributed as external resource packs.
• The obooksrv dataset is now read directly in server.py without an external service.
• Built-in replay mode, while preserving the original PGN Replay engine.
• Refreshed web client experience.

User Manual

• English user manual

Requirements

• Raspberry Pi 3, Pi 4, Pi 5 (aarch64) or a Linux computer (x86_64)
• RaspiOS Bookworm 64bit or Trixie 13 (released in 2025). Wayland is supported. Web/desktop installs default to audio-backend = native. DGTPi clock users may need either native or sox, depending on the Pi audio setup.

Alternatively, use 64-bit Windows 10/11 (x64/AMD64) or macOS on Apple silicon or 64-bit Intel, with native CPython 3.11-3.13. Follow the Windows installation or macOS installation section below.

Quick Installation (Raspberry Pi / Linux)

Get the installation script, give it execution rights, and run it as sudo. It will clone the repository to /opt/picochess and install the needed services. It also downloads a basic set of engines (Stockfish 17.1 and LC0 0.32) plus LC0 weights; downloading the weights can take a while.

• wget -L https://raw.github.com/JohanSjoblom/Picochess/master/install-picochess.sh
• chmod +x install-picochess.sh
• sudo ./install-picochess.sh
• Default engine pack is small. If you want more engines and are OK with a longer download, use sudo ./install-picochess.sh large.
• If PicoChess runs inside a DGTPi clock, use sudo ./install-picochess.sh dgtpi.
• For a standalone DGT3000 connected by cable to a DGT eboard, use sudo ./install-picochess.sh dgt3000; this keeps dgtpi=False because clock communication runs through the eboard.
• If you install on a standard Raspberry Pi 3 without a DGTPi/DGT3000 clock, run: sudo ./install-picochess.sh pi3
• Reboot; Picochess should start as a service.

The script installs the following services in /etc/systemd/system/:

• picochess (main service)
• picochess-update (stay updated)
• gamesdb (games window on web page)
• unblock-bt (installed when using the pi3 or dgtpi parameter; unblocks Bluetooth on boot)

Engine package choice controls contents and download size, independently of headless or desktop use. Both packages work with either setup. lite remains a deprecated alias for large. DGTPi clock support and kiosk setup are separate options.

install-picochess.sh flags:

• pico skips system update (useful on existing systems).
• small (default) installs the minimum pack on a fresh installation and keeps existing engine resources on reruns, even when explicitly supplied. An explicit large triggers an engine backup + reinstall for the current architecture.
• noengines skips installing engines (used internally during code-only updates).
• dgtpi installs the DGTPi GPIO clock service and applies Raspberry Pi 3 clock timing in /boot/firmware/config.txt or /boot/config.txt; do not run install-dgtpi-clock.sh separately.
• dgt3000 or DGT3000 selects a standalone DGT3000 connected through a DGT eboard. It keeps dgtpi=False, removes legacy DGTPi service and clock-timing configuration, and does not install the DGTPi GPIO clock service.
• kiosk installs autologin + kiosk autostart using etc/pico-kiosk.desktop.
• pi3 installs the Bluetooth unblock service (useful on Raspberry Pi 3 with Trixie).
• master switches an existing checkout back to origin/master before installing, useful for leaving a test branch.
• reset backs up and resets picochess.ini and the installed user kiosk.sh to current defaults. Existing DGTPi configuration selects the DGTPi defaults automatically.

When an older standalone DGT3000 installation incorrectly contains dgtpi=True, run the installer once with dgt3000 to select the normal eboard profile and remove legacy DGTPi support. Add reset only when you also want to replace all settings with the current defaults.

On normal updates, an existing user kiosk.sh is refreshed from the repository and its immediately previous contents are saved as kiosk.sh.backup; a later replacement updates that single backup. Add an exact # no update comment line to a customized kiosk.sh to keep it unchanged. Explicit reset mode overrides this marker.

You can safely rerun install-picochess.sh any time. It can fix permissions, refresh services, and is a good first troubleshooting step if something isn’t working.

How to stay updated

You can manually update to latest version from within the program. Go to the System, Power menu and select Restart and Update Picochess. If you really want to stay updated you can edit your picochess.ini file and uncomment the line enable-update = True. In this case it will update the code every time you reboot. It will not run a system update at boot, as that takes quite some time. It will only update the picochess code.

How to open the web page and play?

Use localhost in your browser to open the web page. If you are running on another machine replace localhost with the IP address of your Pi. If you use a firewall, ensure the Picochess web port is allowed. For headless setups (for example DGT3000), you can use your phone browser as both display and audio output instead of local speakers.

Wi-Fi setup (no network on first boot)

If your Pi boots without Wi‑Fi configured, you can set it from the web UI:

1. Connect the Pi to a temporary network (e.g., phone hotspot or Ethernet).
2. Open the web UI and go to Settings → Wi‑Fi.
3. Run sudo ./enable-wifi-setup.sh once on the Pi to allow Wi‑Fi changes.
4. Enter your Wi‑Fi SSID/password and click Connect.
5. After onboarding, you can tighten access by setting allow-onboard-without-auth = false in picochess.ini. Tip: for first‑time setup, the simplest path is to start your phone hotspot, then use System → Wi‑Fi → Hotspot on the clock to connect and get the Pi’s IP on the display.

Cybersecurity notes

• The Wi‑Fi onboarding page is open to private network clients by default to simplify first‑boot setup.
• After onboarding, set allow-onboard-without-auth = false in picochess.ini to require authentication.
• The Settings page always requires authentication.

Bluetooth pairing (experimental)

The pair-phone tool can pair a phone and attempt Bluetooth PAN (tethering). On some phones (notably Samsung), PAN may fail; the flow then falls back to phone hotspot. Consider this feature experimental and optional; it does not affect normal Picochess usage. The primary onboarding path is Wi‑Fi hotspot connection as described above. Optional settings (in picochess.ini):

• bt-pair-pin (default 0000)
• bt-pair-timeout (seconds, default 40)
• hotspot-ssid / hotspot-pass (auto-connect to a phone hotspot after PAN failure) You can also connect directly to a configured phone hotspot from the DGT clock via System → Wi‑Fi → Hotspot.

Kiosk mode (auto-launch on boot)

If you want Picochess to start automatically on a touchscreen, you can run Chromium in kiosk mode after the desktop loads. Note: On RaspiOS Bookworm, kiosk mode is more reliable under X11 than Wayland. If you hit Chromium window sizing issues with Wayland, switch to X11 for kiosk use.

Recommended approach:

1. Copy /opt/picochess/kiosk.sh to your home folder (e.g. /home/pi/kiosk.sh). Most users want to tailor it for their display, so a local copy is easiest to edit.
2. Create an autostart entry:
   • Copy /opt/picochess/etc/pico-kiosk.desktop to ~/.config/autostart/ (create the directory if needed: mkdir -p ~/.config/autostart).
   • If your username is not pi, edit the Exec= path in that file.

The kiosk script supervises the Chromium process it starts. Chromium closes when PicoChess stops and opens again if the service is restarted; normal Chromium sessions are not affected. On normal updates, an existing ~/kiosk.sh is refreshed from the repository and its previous contents are saved as ~/kiosk.sh.backup. To keep a customized kiosk script unchanged, add an exact # no update comment line to it. Explicit reset mode overrides this marker.

How to analyse a PGN game using Picotutor?

You can upload a PGN game. Go to localhost/upload and choose a PGN file to upload to Picochess. It will ask you for your pi user password. It will load the PGN game into the starting position. Now you can step through the PGN game in Picochess by using the play-pause button. Finally save the game from the menu if you want to store the evaluations. Uploads are written to /opt/picochess/games/upload. Games are saved in /opt/picochess/games. To upload a game from your mobile phone to Picochess you need to know the IP address of your Pi computer and replace localhost above with the IP address. You also need to be on the same network as your Pi computer. If you want to load the last game choose "PGN Replay" mode. For more analysis modes, continue reading below.

How to enter and analyse a game using Picotutor?

You can use the menu to go to Mode and switch to "Hint On", "Eval.Score", "Observe" or "Analysis" mode. Now you make moves for both sides. Use the plus and minus button to check the depth-score and hit move. When you are done analysing: use the Game Setup from the menu and chose Declare game ending. Your game with picotutor evaluations are saved in /opt/picochess/games/last_game.pgn.

Additional scripts you might find useful:

• connect-dgt-on-debian.sh, use this on Linux laptops to be able to connect to a Bluetooth DGT e-board (edit the script to add your eboard MAC address).
• Fix_bluetooth.sh, BLE reset and compatibility setup for Raspberry Pi OS Trixie (run with sudo).
• check-bluetooth.sh, collect Bluetooth diagnostics into bluetooth.txt for troubleshooting (run with sudo).
• install-kiosk.sh, enable autologin and kiosk autostart (run with sudo).
• install-ydotool.sh, optional helper for Wayland users; installs and configures ydotool, including Trixie backports when needed (run with sudo).
• check-config.sh, validate picochess.ini for common mistakes.
• pair-phone, interactive phone pairing tool with clock prompts (run with sudo).
• bt-pan-connect, Bluetooth PAN helper (run with sudo).
• enable-wifi-setup.sh, allow the web onboarding page to run nmcli (run with sudo once).
• wifi-hotspot-connect, connect to a configured phone hotspot (run with sudo).

How to add more engines?

Picochess ships with engine resource packs. The installer runs install-engines.sh once after cloning and installs the default small pack (includes Stockfish and LC0). You can re-run install-engines.sh anytime; it only downloads folders that are missing.

To update existing engine packs or switch from small to large while keeping collected ROMs and your retro menu selection:

cd /opt/picochess
./update-engines.py large --dry-run
sudo systemctl stop picochess
./update-engines.py large
# Only restart after a successful update:
sudo systemctl start picochess

Run the updater without sudo. It detects aarch64 or x86_64, stages the new packs, and retains a dated backup. See engine update details for preserved files, runtime requirements and rollback. The older move-engines-to-backup.sh plus install-engines.sh workflow, also used by an explicit large reinstall through install-picochess.sh, remains a clean reinstall that requires manual restoration of user data.

The large package takes longer to download. Both package sizes download the shared LC0 personality weights into /opt/picochess/engines/lc0_weights, including Tiny Gyal and the Maia strengths. The v4.4.1 weights archive is architecture-independent and is also usable by LC0 on other operating systems. Existing weights folders are left untouched. To refresh the collection, move the entire weights folder to backup first. To add more engine manually yourself you need:

• locate the /opt/picochess/engines folder - Pi uses aarch64 and Linux x86_64 folder
• add an executable engine file like "engineX" and a text file "engineX.uci" with the settings for that engine
• add an [engineX] section in engines.ini file

Books and games database resources

Opening books and the games database are downloaded as external resources via install-picochess.sh (or install-books-games.sh). Once downloaded, they are user-managed and won't be overwritten by normal code updates. The obooksrv/opening.data file is also user-managed; if it is missing, install-books-games.sh will download it. The book selector in the web client is independent from the engine opening book; the engine uses the book configured in picochess.ini. The web book tab also includes an obooksrv entry; selecting it shows statistics from the local opening.data dataset, while other entries use the selected polyglot .bin book. To add a custom book, place the .bin file in books/ and add a matching entry in books/books.ini.

Windows installation

The experimental native Windows port has a non-administrative PowerShell installer. It creates or reuses a Python 3.11-3.13 x64/AMD64 virtual environment and installs the small Windows engine pack, books, opening data, and games database data by default. It does not install Windows services:

.\install-picochess-windows.ps1

Windows users can also supply their own native UCI engines under engines\AMD64. See the Windows installation guide and the engine setup guide for details and current limitations. A graphical installer and control panel are documented in win/README.md.

If the user has separately installed Scid vs. PC for Windows, start-picochess-windows.ps1 can start its tcscid.exe games helper together with PicoChess. Failure to find Scid affects only the optional Games tab.

macOS installation

The native macOS installer follows the same user-local approach. It supports Apple silicon and 64-bit Intel Macs, creates a native Python 3.11-3.13 virtual environment, and installs a Stockfish starter engine when the native engine directory is absent. It also installs the portable data resources without adding system services:

bash ./install-picochess-mac.sh

macOS users can supply their own native UCI engine under engines/arm64 on Apple silicon or engines/mac_x86_64 on Intel. An existing architecture directory is left untouched. See the macOS installation guide for options and limitations. An experimental graphical control panel for installation, startup, and upgrades is documented in mac/README.md.

Installation with more detailed info

1. You need a Raspberry PI 5, 4, or 3. You also need a 32G SD card.
2. Use Raspberry Pi Imager to create a PI operating system on your SD card as follows:
3. Choose PI 4 and 64bit OS (I have not tested PI 3 yet, but feel free to test)
4. Username is typically pi (default in Raspberry Pi Imager). The user you install with should be the same account that runs picochess as a service. Installing under a different user than you log in with may cause permission issues (for example, updates).
5. If you don't not use a network cable on your PI remember to define your WiFi settings.
6. Add ssh support if you don't work locally on your Raspberry Pi with attached screen, keyboard and mouse.
7. Write the image to the SD.
8. Boot your PI with the SD card inserted. A standard image will reboot after first start, and the second time it starts you should be able to login as user pi.
9. Using sudo raspi-config, keep the default PipeWire setup on desktop installs. Web/desktop installs default to audio-backend = native. DGTPi clock users may need either native or sox, depending on the Pi audio setup; when installed with sudo ./install-picochess.sh dgtpi, the installer also configures Raspberry Pi 3 clock timing. Wayland is supported; X11 is optional. The install script now installs the native audio runtime libraries, including pipewire-alsa, only when audio-backend is not set to sox.
10. Get this repo. First cd /opt then do sudo git clone. This should create your /opt/picochess folder. Alternative: Download the install-picochess.sh script and run it using sudo. See quick installation above.
11. Run the install-picochess.sh script. The script will first do a system update which may run for a while depending on how old your installation is. Then it will do git clone if you dont have the repo, and git pull if you already have the repo in /opt/picochess.
12. Reboot when install is done. When you login again the voice should say "picochess", "engine startup", "ok".
13. Open your web browser on localhost or from another computer using the IP address of your PI. You can change the web port in picochess.ini
14. Start playing !

Tailoring: edit the picochess.ini file. Troubleshooting: check the log in /opt/picochess/logs/picochess.log Google group for reporting and discussing: https://groups.google.com/g/picochess

Playing chess variants

Install the Fairy-Stockfish 14 engine along with fairy.uci and enable it in engines.ini to play some fun chess variants. Five variants are implemented as engine levels, each with four Elo strengths (1000, 1500, 2000, 2850):

1. Three-Check: in addition to the normal rules of chess, you win the game immediately when you check your opponent for the third time in the game (not necessarily consecutive checks).
2. King of the Hill: in addition to the normal rules of chess, the player who reaches d4, d5, e4 or e5 in a legal way with his king, wins the game immediately.
3. Atomic Chess: captures trigger an explosion that destroys the capturing piece, the victim, and all surrounding non-pawn pieces within a one-square radius.
4. Racing Kings: the player whose king reaches the 8th rank first, wins. No checks allowed!
5. Antichess: the player who loses all his pieces first or gets stalemated, wins.

Screenshots

Note

This repository does not contain all engines, books or voice samples the community has built over the years. Unfortunately, a lot of those files cannot be easily hosted in this repository. You can find additional content for your picochess installation in the Picochess Google Group.