♟️ Update: now used on the 2nd-biggest chess website, the fully open-source and non-profit lichess.org (see announcement here)

ChessQueries

Chess board recognition: provide a photo of a real-life chessboard and receive its chess position.

🌐 Demo · 📄 Paper · 📊 Dataset · 🤖 Model weights

Try it online. The website uses a ChessQueries model further trained on proprietary data.

Model

ChessQueries consists of a 304M-parameter ViT-L/14 encoder that maps a 644 × 644 input image to patch tokens. Sixty-four learned queries—one for each board square—cross-attend to those tokens through a DETR-style decoder. A single shared linear head maps each decoded query to its per-square class.

Best exact-board accuracy reported in the paper for a model trained on the ChessReD, ChessCog, and SLCC training splits:

Quick start

ChessQueries requires Python 3.12 and Poetry. Install the visualizer and launch the local Gradio demo:

poetry install --with viz
poetry run chessqueries-demo

You can also predict directly from one or more images:

poetry run chessqueries-predict photo.jpg --viz prediction.png

On first use, both commands download and verify the FP16 paper ViT-L safetensors checkpoint, then cache it under checkpoints/release/. CUDA runs in FP16; CPU uses the same download with FP32 arithmetic. Preprocessing stays FP32; the default batch size is one.

For other checkpoints and their download instructions, see the Hugging Face pages for paper models and ChessQ Lite.

Citation

@misc{seytre2026chessqueries,
  title         = {ChessQueries: Toward Better Chess Board Recognition},
  author        = {Seytre, Jo{\"e}l},
  year          = {2026},
  eprint        = {2608.30762},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CV},
  doi           = {10.48550/arXiv.2608.30762},
  url           = {https://arxiv.org/abs/2608.30762}
}

Licenses

• Code — PolyForm Noncommercial 1.0.0, including the required notice: Copyright (c) 2026 the chessqueries authors.
• Model weights — PolyForm Noncommercial 1.0.0.
• SLCC annotations — CC BY-NC 4.0. The source broadcasts and reconstructed frames are not distributed and remain the property of their respective rights holders.

Commercial use is not licensed.

Going further

See DEVELOPMENT.md for repository layout, data preparation, training and evaluation commands, experiment utilities, and checks.

See the minimal reproduction guide for a self-contained implementation of the model, training, evaluation, and leakage checks used in the paper.

Contact

Questions and enquiries: contact "at" chessq.org