# Lichess Chess Puzzles Database

## Facts

- Provider: Lichess (lichess.org)
- License: CC0-1.0 (https://database.lichess.org/)
- Size: 5 files
- Format: Parquet (in sampled files)
- Stored at: Hugging Face, https://huggingface.co/datasets/Lichess/chess-puzzles
- Access: public, readable without an account
- Category: Machine Learning & AI
- Source: https://database.lichess.org/#puzzles
- Page: https://scigantic.com/archive/45023618-5555-5164-90c5-3d29952a286c
- Keywords: Machine Learning & AI, Parquet, Hugging Face

## About

Tactical chess puzzles generated from real Lichess games, rated and tagged by theme. The card reports 6,157,341 puzzles, updated monthly. Generating the initial set took more than 50 years of CPU time: Lichess went through 300 million analysed games and re-analysed interesting positions with Stockfish 12 to 15 NNUE at 40 meganodes, then players solving the puzzles on lichess.org produced Glicko-2 ratings for them. Each row holds a puzzle id, the source game id and move, the starting position as FEN, the solution as UCI moves, the puzzle rating and rating deviation, popularity, number of plays, theme tags (fork, pin, mate in 2, endgame and so on) and opening tags. Listing data/ (measured 2026-11-14) shows three Parquet shards of about 0.3 GB. Uses include tactics training, measuring the reasoning ability of chess engines and language models, puzzle difficulty prediction, curriculum learning and studies of human problem solving. Load it with Hugging Face datasets, pandas or pyarrow and replay solutions with python-chess. Lichess releases its database exports under CC0.

## Load the data

```python
from datasets import load_dataset
ds = load_dataset("Lichess/chess-puzzles")
print(ds)
```

## Data structure

File types in sampled files: Parquet

Example file: `data/train-00000-of-00003.parquet`

## Open it

- In a hosted notebook with the data mounted: https://scigantic.com/archive/45023618-5555-5164-90c5-3d29952a286c
- Full record as JSON (schema card included): https://api.scigantic.com/api/archives/45023618-5555-5164-90c5-3d29952a286c
- Over MCP: `get_schema_card` with id `45023618-5555-5164-90c5-3d29952a286c` at https://api.scigantic.com/mcp

## Related topics

- [Parquet datasets](https://scigantic.com/topics/parquet)
- [Machine Learning & AI datasets](https://scigantic.com/topics/machine-learning-and-ai)
