Suite complète d'outils CLI pour télécharger, transformer et s'entraîner sur les puzzles d'échecs de la base Lichess. 🎯
Composants :
- 🌐
download_puzzles.sh: Téléchargement et décompression automatique - 🔧
extract.py: Transformation des puzzles (calcul du FEN après premier coup) - 🎮
puzzle_trainer.py: Entraînement interactif avec vérification des coups
- Prérequis système
- Installation de l'environnement Python
- Téléchargement de la base Lichess
- Extraction et transformation des puzzles
- Entraînement interactif
- Workflow complet
- Configuration avancée
- Informations techniques
- Troubleshooting
Avant de commencer, vous devez installer les binaires nécessaires sur votre système.
# Mise à jour des dépôts
sudo apt update
# Installation des outils nécessaires
sudo apt install -y python3 python3-venv wget zstd
# Vérification des versions installées
python3 --version # Python 3.7+ requis
wget --version
zstd --version- python3 : Interpréteur Python pour exécuter les scripts
- python3-venv : Module pour créer des environnements virtuels isolés
- wget : Télécharge la base de données Lichess
- zstd : Décompresse le fichier
.zst(Zstandard compression)
# Créer le répertoire (si nécessaire)
mkdir -p ~/mat-en
# Se placer dedans
cd ~/mat-en# Création du venv (environnement Python isolé)
python3 -m venv venv
# Activation du venv
# IMPORTANT : à faire à chaque nouvelle session terminal
source venv/bin/activate
# Votre prompt devrait maintenant afficher (venv) au débutExplication : Le venv isole les bibliothèques Python pour ne pas polluer le système. Tout ce qui est installé via pip reste dans ~/mat-en/venv/.
# S'assurer que le venv est activé (vous devez voir (venv) dans le prompt)
pip install python-chess
# Vérification de l'installation
python3 -c "import chess; print(chess.__version__)"# Télécharger ou créer les scripts, puis les rendre exécutables
chmod +x download_puzzles.sh
chmod +x extract.py
chmod +x puzzle_trainer.py~/mat-en/
├── venv/ # Environnement virtuel Python
├── download_puzzles.sh # Script de téléchargement
├── extract.py # Script de parsing Python
└── puzzle_trainer.py # Trainer interactif
Le script download_puzzles.sh automatise le téléchargement et la décompression.
# Se placer dans le répertoire
cd ~/mat-en
# Lancer le script
./download_puzzles.sh- Vérifie que
wgetetzstdsont installés - Télécharge
lichess_db_puzzle.csv.zst(~263 Mo) - Décompresse le fichier en
lichess_db_puzzle.csv(~1.5 Go) - Affiche des statistiques sur le fichier
=== Téléchargement de la base Lichess Puzzles ===
Vérification des binaires...
✓ wget et zstd sont disponibles
Téléchargement de lichess_db_puzzle.csv.zst (~263 Mo)...
--2025-11-11 10:30:00-- https://database.lichess.org/lichess_db_puzzle.csv.zst
[...]
Saving to: 'lichess_db_puzzle.csv.zst'
100%[================================>] 263.00M 5.20MB/s in 51s
Décompression...
lichess_db_puzzle.csv.zst: 1560823808 bytes
=== Terminé ===
Fichier compressé : 263M
Fichier décompressé : 1.5G
Nombre de lignes : 5524872
Prêt à parser avec extract.py !
Si vous relancez le script alors que les fichiers existent déjà, il vous demandera si vous voulez les remplacer :
Le fichier existe déjà. Remplacement ? (y/N)- Répondez
ypour télécharger/décompresser à nouveau - Répondez
NouEntréepour garder le fichier existant
Le script extract.py transforme les puzzles Lichess en positions FEN exploitables.
IMPORTANT : À chaque fois que vous ouvrez un nouveau terminal, vous devez activer le venv :
cd ~/mat-en
source venv/bin/activateVous devriez voir (venv) apparaître dans votre prompt.
./extract.py [OPTIONS] fichier.csv > sortie.csv| Option | Description | Exemple |
|---|---|---|
--help |
Affiche l'aide | ./extract.py --help |
--mat-en N |
Filtre les mats en N coups (1-5) | --mat-en 1 |
--no_id |
Exclut le PuzzleId de la sortie | --no_id |
--verbose ou -v |
Affiche la progression | --verbose |
PuzzleId,FEN_après_coup_adversaire,Solution,URL,OpeningTags
FEN_après_coup_adversaire,Solution,URL,OpeningTags
# Avec IDs (pour sauvegarde)
./extract.py --mat-en 1 --verbose lichess_db_puzzle.csv > mat1_avec_id.csv
# Sans IDs (pour le trainer)
./extract.py --mat-en 1 --no_id --verbose lichess_db_puzzle.csv > mat1.csvSortie console :
# Démarrage du traitement...
# 10000 puzzles traités | dernier coup: b4b7 | ligne 21834
# 20000 puzzles traités | dernier coup: d7f8 | ligne 43878
[...]
# Terminé: 767302 puzzles traités sur 5524872 lignes
Temps d'exécution : ~5-6 minutes sur Raspberry Pi 4
# Boucle pour générer mat1.csv à mat5.csv (sans IDs)
for i in {1..5}; do
echo "Extraction des mats en $i..."
./extract.py --mat-en $i --no_id --verbose lichess_db_puzzle.csv > mat${i}.csv
echo "✓ mat${i}.csv créé"
done
# Vérifier les tailles
wc -l mat*.csvTemps total : ~20-25 minutes sur Raspberry Pi 4 pour les 5 niveaux
Le script puzzle_trainer.py est un trainer interactif en mode CLI pour s'entraîner sur les puzzles.
- Au moins un fichier
mat*.csvdoit exister dans le répertoire
cd ~/mat-en
./puzzle_trainer.py============================================================
🏆 LICHESS PUZZLE TRAINER 🏆
============================================================
Fichiers de puzzles disponibles :
[1] Mat en 1 coup(s) - 767,302 puzzles
[3] Mat en 3 coup(s) - 523,441 puzzles
[4] Mat en 4 coup(s) - 156,782 puzzles
[Q] Quitter
Choisissez votre niveau :
🎯 PUZZLE - Mat en 1 coup(s)
Ouverture: Sicilian_Defense Sicilian_Defense_McDonnell_Attack
Position FEN :
r4rk1/pp3ppp/3b4/2p1pPB1/7N/2PP3n/PP4PP/R2Q2RK b - - 0 18
URL Lichess: https://lichess.org/d04UP3XD#35
Prêt à valider votre génie tactique ? 🧠
Entrez votre coup en notation UCI (ex: d6h2) ou 's' pour la solution:
>
✅ Détection automatique des fichiers mat*.csv disponibles
✅ Mats en plusieurs coups pris en charge
✅ Vérification des coups - valide si votre coup est correct
✅ Phrases amusantes variées
✅ Statistiques de session - taux de réussite en temps réel
✅ Interface colorée avec émojis
✅ Historique des puzzles (si fichier avec IDs) - ne retombe jamais sur le même puzzle
✅ Gestion des formats : avec ou sans IDs
✅ Commandes :
- Taper votre coup (ex:
h3f2) spour voir la solution sans tenterqpour quitter à tout momentcpour continuer après un puzzle
$ ./puzzle_trainer.py
============================================================
🏆 LICHESS PUZZLE TRAINER 🏆
============================================================
Fichiers de puzzles disponibles :
[1] Mat en 1 coup(s) - 767,302 puzzles
[3] Mat en 3 coup(s) - 523,441 puzzles
[Q] Quitter
Choisissez votre niveau : 1
ℹ Format détecté: Sans IDs (fichier généré avec --no_id)
⚠ L'historique des puzzles vus ne sera pas sauvegardé
============================================================
🎮 SESSION - Mat en 1 coup(s)
============================================================
🎯 PUZZLE - Mat en 1 coup(s)
Position FEN :
2kr1b1r/p1p2pp1/2pqN3/7p/6n1/2NPB3/PPP2PPP/R2Q1RK1 b - - 0 13
URL Lichess: https://lichess.org/seIMDWkD#25
Vous donnez votre langue au chat ? 😺
Entrez votre coup en notation UCI (ex: d6h2) ou 's' pour la solution:
> d6h2
✓ Bravo ! 🎉 Le coup d6h2 est correct !
────────────────────────────────────────────────────────────
[C]ontinuer ou [Q]uitter ? c
[... autre puzzle ...]
============================================================
📊 STATISTIQUES DE LA SESSION
============================================================
Puzzles tentés: 15
Puzzles réussis: 12
Taux de réussite: 80.0%
Merci d'avoir joué ! À bientôt camarade 🤘# Lancer le trainer et rediriger les erreurs dans un fichier
./puzzle_trainer.py 2> errors.log
# Utiliser screen pour une session détachable
screen -S chess
./puzzle_trainer.py
# Ctrl+A puis D pour détacher
# screen -r chess pour rattacherVoici le workflow recommandé du téléchargement à l'entraînement.
# 1. Installer les dépendances système
sudo apt update
sudo apt install -y python3 python3-venv wget zstd
# 2. Créer l'environnement
mkdir -p ~/mat-en
cd ~/mat-en
# 3. Setup Python
python3 -m venv venv
source venv/bin/activate
pip install python-chess
# 4. Rendre les scripts exécutables
chmod +x *.sh *.py# 1. Activer le venv
cd ~/mat-en
source venv/bin/activate
# 2. Télécharger la base Lichess
./download_puzzles.sh
# 3. Extraire tous les niveaux (mat1 à mat5)
for i in {1..5}; do
echo "Extraction niveau $i..."
./extract.py --mat-en $i --no_id --verbose lichess_db_puzzle.csv > mat${i}.csv
done
# Vérification
ls -lh mat*.csvTemps total : ~20 minutes sur Raspberry Pi 4 (téléchargement + extraction)
Éditez extract.py, ligne ~15 :
# Affiche un message tous les X puzzles traités
VERBOSE_INTERVAL = 10000Valeurs recommandées :
5000: affichage toutes les ~1-2 secondes (très verbeux)10000: affichage toutes les ~3-5 secondes (recommandé)50000: affichage toutes les ~15-20 secondes (peu de spam)
Éditez puzzle_trainer.py, ligne ~20 :
PHRASES_FUN = [
"Vous donnez votre langue au chat ? 😺",
"Alors, trouvé le coup gagnant ? 🤔",
# Ajoutez vos propres phrases ici !
"Échec et mat ou échec tout court ? 🤨",
]Si vous voulez recommencer à zéro :
# Supprimer l'historique d'un niveau spécifique
rm .puzzles_history_mat1
# Supprimer tout l'historique
rm .puzzles_history_*# Seulement mat1 et mat3
./extract.py --mat-en 1 --no_id --verbose lichess_db_puzzle.csv > mat1.csv
./extract.py --mat-en 3 --no_id --verbose lichess_db_puzzle.csv > mat3.csvTests sur Raspberry Pi 4 (4 Go RAM) :
| Opération | Temps | Détails |
|---|---|---|
| Téléchargement | ~51 secondes | 263 Mo @ 5 Mo/s |
| Décompression | ~15 secondes | zstd → 1.5 Go |
| Extraction Python (par niveau) | ~5-6 minutes | Calcul FEN avec python-chess |
| Extraction Perl (filtrage simple) | ~56 secondes | Sans transformation FEN |
| Trainer (chargement puzzle) | <1 seconde | Instantané |
PuzzleId,FEN,Moves,Rating,RatingDeviation,Popularity,NbPlays,Themes,GameUrl,OpeningTags
Exemple de ligne :
000rZ,2kr1b1r/p1p2pp1/2pqb3/7p/3N2n1/2NPB3/PPP2PPP/R2Q1RK1 w - - 2 13,d4e6 d6h2,755,80,100,339,kingsideAttack mate mateIn1 oneMove opening,https://lichess.org/seIMDWkD#25,Scandinavian_Defense
Entrée (ligne CSV Lichess) :
000rZ,2kr1b1r/p1p2pp1/2pqb3/7p/3N2n1/2NPB3/PPP2PPP/R2Q1RK1 w - - 2 13,d4e6 d6h2,[...]
Le soucis est que le FEN n'est pas jouable immédiatement, puisqu'un coup doit être joué avant de résoudre le puzzle. Plutôt que de tout parser rapidement tel quel en Perl, j'ai préféré passer par Python Chess et faire jouer chacun des coups avant d'enregistrer le FEN "prêt à résoudre"
Traitement :
- Parse le FEN :
2kr1b1r/p1p2pp1/2pqb3/7p/3N2n1/2NPB3/PPP2PPP/R2Q1RK1 w - - 2 13 - Joue le premier coup
d4e6avecpython-chess - Calcule le nouveau FEN
- Extrait la solution :
d6h2
Sortie (CSV transformé) :
000rZ,2kr1b1r/p1p2pp1/2pqN3/7p/6n1/2NPB3/PPP2PPP/R2Q1RK1 b - - 0 13,d6h2,https://lichess.org/seIMDWkD#25,Scandinavian_Defense
Le nouveau FEN représente la position exacte à résoudre.
lichess_db_puzzle.csv.zst : 263 Mo (compressé)
lichess_db_puzzle.csv : 1.5 Go (5 524 872 lignes)
mat1.csv : ~90 Mo (767 302 lignes)
mat2.csv : ~110 Mo (916 465 lignes)
mat3.csv : ~75 Mo (523 441 lignes)
mat4.csv : ~23 Mo (156 782 lignes)
mat5.csv : ~8 Mo (51 329 lignes)
.puzzles_history_mat* : <1 Ko (IDs des puzzles vus)
Exemples de coups UCI :
e2e4: pion de e2 vers e4g1f3: cavalier de g1 vers f3e7e8q: promotion en dame (pion e7 → e8)e1g1: petit roque (roi e1 → g1)
Le trainer accepte les coups en minuscules sans distinction.
Erreur :
✗ Aucun fichier mat*.csv valide trouvé dans le répertoire actuel !
Solution :
# Vérifier votre répertoire actuel
pwd # Doit être ~/mat-en
# Lister les fichiers
ls -la mat*.csv
# Si pas de fichiers, générer avec extract.py
source venv/bin/activate
./extract.py --mat-en 1 --no_id lichess_db_puzzle.csv > mat1.csvSymptôme : Pas de (venv) dans le prompt
Erreur possible :
ModuleNotFoundError: No module named 'chess'
Solution :
cd ~/mat-en
source venv/bin/activate
# Vérifier
which python3 # Doit pointer vers ~/mat-en/venv/bin/python3Astuce : Créer un alias dans ~/.bashrc :
alias activ='cd ~/mat-en && source venv/bin/activate'Erreur :
bash: ./extract.py: Permission denied
Solution :
chmod +x download_puzzles.sh extract.py puzzle_trainer.pyErreur :
Erreur: wget n'est pas installé
Solution :
# Debian/Ubuntu
sudo apt install wget zstd
# FreeBSD
pkg install wget zstdErreur :
✗ Format CSV invalide dans mat1.csv (moins de 3 colonnes)
Causes possibles :
- Fichier corrompu lors de la génération
- Redirection mal faite (écrasement partiel)
- Fichier vide
Solution :
# Vérifier le fichier
head -3 mat1.csv
wc -l mat1.csv
# Si problème, régénérer
source venv/bin/activate
./extract.py --mat-en 1 --no_id --verbose lichess_db_puzzle.csv > mat1.csvC'est normal : Le calcul du nouveau FEN avec python-chess prend du temps.
Solutions :
- Laissez tourner en arrière-plan :
nohup ./extract.py ... > output.csv & - Utilisez
screenoutmuxpour détacher la session - Exécutez la nuit sur un Raspberry Pi
- Pour filtrage rapide sans FEN : utilisez le script Perl (si disponible)
Symptôme : Le trainer redemande les mêmes puzzles
Cause : Fichier CSV généré avec --no_id
Explication : Sans IDs uniques, impossible de tracker les puzzles vus.
Solutions :
- Régénérer avec IDs (recommandé pour tracking) :
./extract.py --mat-en 1 --verbose lichess_db_puzzle.csv > mat1_avec_id.csv- Accepter que les puzzles se répètent (mode aléatoire pur)
Symptôme : Le trainer affiche des codes comme \033[92m
Cause : Terminal ne supporte pas les codes ANSI
Solution :
- Utilisez un terminal moderne (bash, zsh)
- Sur Windows : utilisez WSL ou Windows Terminal
Erreur :
✗ Impossible de trouver un puzzle valide après 10 tentatives
Causes :
- Fichier CSV très corrompu
- Format complètement invalide
Solution :
# Vérifier l'intégrité du fichier
head -20 mat1.csv | cat -A # Affiche les caractères cachés
# Régénérer le fichier
rm mat1.csv
./extract.py --mat-en 1 --no_id --verbose lichess_db_puzzle.csv > mat1.csv~/mat-en/
├── venv/ # Environnement virtuel Python
│ ├── bin/
│ │ ├── python3
│ │ ├── pip
│ │ └── activate
│ ├── lib/
│ └── ...
├── download_puzzles.sh # Script de téléchargement
├── extract.py # Parser Python (transformation FEN)
├── puzzle_trainer.py # Trainer interactif
├── lichess_db_puzzle.csv.zst # Base compressée (263 Mo)
├── lichess_db_puzzle.csv # Base décompressée (1.5 Go)
├── mat1.csv # Mats en 1 (767k lignes)
├── mat2.csv # Mats en 2 (916k lignes)
├── mat3.csv # Mats en 3 (523k lignes)
├── mat4.csv # Mats en 4 (156k lignes)
├── mat5.csv # Mats en 5 (51k lignes)
├── .puzzles_history_mat1 # Historique des puzzles vus (niveau 1)
├── .puzzles_history_mat2 # Historique niveau 2
└── ... # Autres historiques
# Installation initiale (une seule fois)
cd ~/mat-en
python3 -m venv venv
source venv/bin/activate
pip install python-chess
chmod +x *.sh *.py
# Télécharger la base
./download_puzzles.sh
# Extraire tous les niveaux
for i in {1..5}; do
./extract.py --mat-en $i --no_id --verbose lichess_db_puzzle.csv > mat${i}.csv
done
# Désactiver le venv
deactivate
# Utilisation quotidienne
cd ~/mat-en
./puzzle_trainer.py
# Seulement les mats en 1 avec ouvertures siciliennes
grep "Sicilian" lichess_db_puzzle.csv | ./extract.py --mat-en 1 --no_id > mat1_sicilian.csv
# Les 100 premiers mats en 2
./extract.py --mat-en 2 --no_id lichess_db_puzzle.csv | head -100 > mat2_sample.csv# Combien de puzzles de niveau 1 avez-vous vus ?
wc -l .puzzles_history_mat1
# Pourcentage de progression
TOTAL=$(wc -l < mat1.csv)
SEEN=$(wc -l < .puzzles_history_mat1)
echo "scale=2; $SEEN * 100 / $TOTAL" | bc# Sauvegarder vos progressions
tar -czf chess_backup_$(date +%Y%m%d).tar.gz .puzzles_history_*
# Restaurer sur une autre machine
tar -xzf chess_backup_20251111.tar.gz- Base Lichess : https://database.lichess.org/
- Documentation python-chess : https://python-chess.readthedocs.io/
- Notation UCI : https://www.chessprogramming.org/UCI
- Lichess Analysis : https://lichess.org/analysis (pour tester les FEN, mais désactiver l'analyse pour ne pas avoir la solution immédiatememennt !)
Développement : DeuZa - Novembre 2025
Ancien DBA Oracle Senior @ Club-Internet
Hacker, activiste digital, passionné d'échecs
Remerciements :
- Lichess.org pour la base de données publique <3
- Lichess.org pour proposer l'équivalent de ce qui est payant ailleurs entiérement gratuit et open-source <3
- La communauté python-chess
- Tous les contributeurs open source et fournisseurs de data love
Les données Lichess sont sous licence Creative Commons CC0 (domaine public). Les scripts de ce projet également sous licence CC0 (domaine public), faites en ce que vous voulez.
- 🎨 Interface TUI (Text User Interface) avec
richoutextual - 📊 Graphiques de progression avec
matplotlib - 🌐 Mode multi-joueurs en réseau
- 🤖 Intégration avec Stockfish pour analyses
- 📱 Export vers Anki pour révisions espacées
- 🏆 Système de badges et achievements
- ⏱️ Mode chronomètre pour puzzles rapides
- 💾 Export des statistiques en JSON/CSV
Si vous avez des idées ou contributions, n'hésitez pas ! 🚀
**Bon entraînement aux échecs ! **