Schachrepertoire mit Stockfish bereinigen: Der PGN Repertoire Cleaner

Du hast deine Partien als PGN gesammelt, importierst sie in ein Schachprogramm und möchtest daraus ein Eröffnungsrepertoire machen. Klingt vernünftig. Nur: In diesen Partien stehen auch deine Fehler. Wer die Zugfolgen ungeprüft übernimmt, übt womöglich genau die Fortsetzung ein, die ihn beim letzten Mal in Schwierigkeiten gebracht hat.

Der Chess Opening Repertoire Cleaner setzt an dieser Stelle an. Das frei verfügbare Python-Skript untersucht PGN-Partien mit einer lokalen Stockfish-Engine. Es findet den ersten ausreichend großen Bewertungsverlust einer gewählten Farbe, ersetzt diesen Zug durch den besten gefundenen Engine-Zug und beendet die neue Trainingslinie dort. Aus einer gespielten Partie wird so ein Ausgangspunkt für bessere Vorbereitung.

Hier erfährst du, wie du dein Schachrepertoire mit Stockfish bereinigen kannst, welche Einstellungen wirklich zählen und warum ein korrigierter Zug erst der Anfang des Lernens ist. Mit einer nachvollziehbaren Anleitung für Windows, macOS und Linux, und einem Blick auf die Grenzen der Methode.

Was macht der Repertoire Cleaner genau?

Mein Projekt findest du auf GitHub: Chess Opening Repertoire Cleaner. Der Name des ausführbaren Skripts lautet opening_cut_replace_mistakes.py. Es ist ein Kommandozeilenwerkzeug: Du startest es im Terminal beziehungsweise in PowerShell. Eine eigene grafische Brettoberfläche gehört nicht dazu.

Für jede Partie geht das Skript die Hauptzugfolge durch. Bei Zügen der ausgewählten Farbe berechnet Stockfish zwei Dinge: die Bewertung des besten gefundenen Zuges und die Bewertung des tatsächlich gespielten Zuges. Für die zweite Berechnung wird die Engine auf diesen Zug festgelegt. Beide Analysen verwenden das gewählte Rechenlimit.

• Du legst fest, ob Weiß oder Schwarz untersucht wird.
• Du kannst die Fehlersuche erst ab einem bestimmten Zug beginnen lassen.
• Du bestimmst, welcher Bewertungsunterschied als Fehler gelten soll.
• Du kannst den untersuchten Bereich auf die ersten Halbzüge der Partie beschränken.
• Beim ersten Treffer werden die vorherigen Züge übernommen und der beanstandete Zug ersetzt. Die ursprüngliche Fortsetzung entfällt.

Entscheidend: Es wird pro Partie nur ein Zug ersetzt. Das Skript erzeugt weder eine vollständige neue Partie noch automatisch mehrere korrekte Antwortvarianten. Es liefert kurze Linien mit einem Korrekturpunkt, an dem deine weitere Analyse beginnt.

Warum eigene Partien eine gute Grundlage sind

Ein Eröffnungsbuch zeigt dir, was theoretisch vorkommen kann. Deine eigenen Partien zeigen dir zusätzlich, was dir tatsächlich begegnet. Wenn im Verein immer wieder dieselbe Nebenvariante aufs Brett kommt, verdient sie Aufmerksamkeit – auch wenn sie im großen Theoriewerk nur eine Randnotiz ist.

Der Cleaner kann dabei helfen, aus einer größeren Sammlung die Stellen herauszufiltern, an denen deine gespielten Züge gegenüber einer Engine-Alternative deutlich zurückfallen. Das ist besonders praktisch, wenn du nach mehreren Turnieren oder vielen Onlinepartien nicht jede Eröffnung von Hand überprüfen möchtest.

Trotzdem bleibt die Auswahl deiner Eröffnungen eine andere Aufgabe. Welche Systeme zu dir passen und wie groß dein Theorieaufwand sein sollte, behandelt der Beitrag Wie lassen sich Schacheröffnungen lernen?. Der Cleaner hilft anschließend bei der Pflege konkreter Zugfolgen.

Was bedeutet „Fehler“ in diesem Programm?

Ein Fehler ist hier keine pädagogische Kategorie wie „Entwicklung vernachlässigt“. Er ist ein gemessener Unterschied zwischen zwei Engine-Bewertungen. Erreicht dieser Unterschied die eingestellte Schwelle, und ist der gefundene beste Zug ein anderer als der gespielte, wird die Partie an dieser Stelle bearbeitet.

Der Standardwert beträgt 40 Centipawns, also 0,40 Bauerneinheiten. Diese Zahl beschreibt eine Bewertungsskala. Sie bedeutet weder, dass du tatsächlich einen Teil eines Bauern verlierst, noch lässt sie sich pauschal in eine feste Gewinnwahrscheinlichkeit umrechnen.

Ein Rechenbeispiel – ausdrücklich keine gemessene Stellung

Angenommen, Schwarz ist am Zug. Aus schwarzer Sicht ergibt der beste gefundene Zug eine Bewertung von +0,20, während der gespielte Zug bei −0,35 liegt. Die Differenz beträgt 0,55 Bauerneinheiten beziehungsweise 55 Centipawns. Mit einer Schwelle von 40 wird dieser Zug ersetzt; mit einer Schwelle von 80 nicht.

Eine Besonderheit beim Lesen der Ausgabe: Die Bewertungen im eingefügten PGN-Kommentar werden aus weißer Sicht angegeben. Im Beispiel stünden deshalb für den gespielten schwarzen Zug +0,35 und für den besseren schwarzen Zug −0,20. Dass die zweite Zahl kleiner ist, ist für Schwarz gerade die Verbesserung. Der angegebene Verlust bleibt 0,55.

Die Fehlerschwelle ist eine Arbeitsentscheidung. Ein kleiner Wert findet mehr Feinheiten und kann auch gut spielbare persönliche Vorlieben aussortieren. Ein größerer Wert konzentriert die Auswahl eher auf deutliche Verschlechterungen. Für einen ersten Überblick kannst du beispielsweise 80 Centipawns ausprobieren und wichtige Linien später mit einer feineren Schwelle prüfen. Das ist ein praktischer Einstieg, kein objektives Gütesiegel.

Vorbereitung: PGN, Python und Stockfish

• Eine PGN-Datei: Am besten eine überschaubare Auswahl eigener Partien aus denselben Eröffnungen. Für dein Schwarzrepertoire wählst du Partien, in denen du Schwarz hattest; für Weiß entsprechend Weißpartien. Das Programm erkennt deinen Namen nicht automatisch.
• Python ab Version 3.10: Das Skript und seine Pakete laufen in einer lokalen Python-Umgebung.
• Eine lokale Stockfish-Datei: Du musst den Pfad zur ausführbaren Engine kennen. Eine allein in einer Website verfügbare Engine reicht für dieses Skript nicht.
• Das Projekt: Lade es über GitHub herunter oder klone es mit Git. Die erforderlichen Python-Pakete sind in requirements.txt aufgeführt.

Eine Einführung in die Engine findest du unter Stockfish installieren und einbinden. Wenn du zunächst Partiensammlungen suchst, hilft die Übersicht zu Schachpartien und kostenlosen Datenbanken. Für die hier beschriebene persönliche Trainingsarbeit sind deine eigenen Partien meist der gezieltere Start.

Wichtig für deine Dateien: Verwende unterschiedliche Pfade für Eingabe und Ausgabe. Die Ausgabedatei wird zum Schreiben geöffnet und eine bereits vorhandene Datei gleichen Namens dabei überschrieben. Behalte deine Original-PGN unverändert als Archiv.

Installation Schritt für Schritt

1. Projekt herunterladen

Mit installiertem Git kannst du das Repository so klonen:

git clone https://github.com/SHermann42/chess-opening-repertoire-cleaner.git
cd chess-opening-repertoire-cleaner

Ohne Git öffnest du die Projektseite und wählst unter „Code“ den ZIP-Download. Entpacke die Dateien und öffne ein Terminal im Projektordner. Die folgenden Befehle werden dort ausgeführt.

2. Eine eigene Python-Umgebung anlegen

Unter Linux oder macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Unter Windows in PowerShell:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Die Windows-Variante verwendet Python direkt aus der virtuellen Umgebung. Damit ist keine Aktivierung per PowerShell-Skript nötig. In den Windows-Aufrufen unten bleibt dieser Pfad deshalb erhalten.

3. Engine-Pfad prüfen

Der Pfad muss zur ausführbaren Stockfish-Datei führen, nicht nur zu ihrem Ordner. Unter Linux kann er beispielsweise /usr/games/stockfish heißen, bei einer Homebrew-Installation auf einem Apple-Silicon-Mac /opt/homebrew/bin/stockfish. Unter Windows hängt er davon ab, wo du den Download entpackt hast. Pfade mit Leerzeichen gehören in Anführungszeichen.

Ein sinnvoller erster Durchlauf

Beginne mit zehn bis zwanzig passenden Partien. Lege sie als meine-schwarzpartien.pgn in den Projektordner. Der folgende Aufruf untersucht Schwarz, beginnt beim sechsten schwarzen Zug und sucht bis einschließlich des 15. Zugpaares einer normal gestarteten Partie:

python opening_cut_replace_mistakes.py --input "meine-schwarzpartien.pgn" --output "schwarz-training.pgn" --engine "/usr/games/stockfish" --color black --start-move 6 --max-ply 30 --threshold-cp 80 --movetime-ms 500 --engine-timeout 15 --restart-engine-every 100 --debug-progress

Unter Windows lautet derselbe Aufruf beispielsweise so; ersetze den Engine-Pfad durch deinen tatsächlichen Dateinamen:

.\.venv\Scripts\python.exe opening_cut_replace_mistakes.py --input "meine-schwarzpartien.pgn" --output "schwarz-training.pgn" --engine "C:\Tools\Stockfish\stockfish.exe" --color black --start-move 6 --max-ply 30 --threshold-cp 80 --movetime-ms 500 --engine-timeout 15 --restart-engine-every 100 --debug-progress

500 Millisekunden sind hier ein kurzer Suchlauf pro Engine-Analyse, keine Qualitätsgarantie. Für jeden geprüften Zug sind im normalen Ablauf zwei Analysen nötig. Laufzeit und Ergebnis hängen zusätzlich von Computer, Engine und Stellung ab. Interessante Treffer solltest du anschließend mit mehr Rechenbudget überprüfen.

Bei Partien aus der üblichen Ausgangsstellung bedeuten 30 Halbzüge 15 Zugpaare. Bei einer PGN, die erst aus einer späteren Stellung startet, zählt --max-ply die gespeicherten Halbzüge ab diesem Anfang. Für den beschriebenen Arbeitsablauf verwendest du am besten regulär gestartete Partien. Spezialfälle mit SetUp-/FEN-Headern solltest du gesondert prüfen.

Eine leicht übersehene Grenze: --max-ply beschränkt die Suche, nicht pauschal die Länge jeder Ausgabepartie. Wenn du --keep-unmodified setzt, können unveränderte vollständige Partien inklusive Mittel- und Endspiel in der Ausgabe stehen. Für eine Sammlung ausschließlich gefundener Korrekturpunkte lässt du diese Option weg.

Suchtiefe, Zeit oder Knoten: Was passt zu deinem Zweck?

Mit --depth 18 gibst du ein Tiefenlimit vor. Wie lange die Engine dafür braucht, kann von Stellung zu Stellung erheblich variieren. Die angezeigte Suchtiefe ist außerdem keine Zusicherung, dass jede mögliche Variante gleich weit untersucht wurde.

Mit --movetime-ms 500 lässt sich der Aufwand eines ersten Durchlaufs leichter abschätzen. Die dabei erreichte Suchtiefe kann unterschiedlich ausfallen. --nodes 50000 begrenzt stattdessen die Zahl der durchsuchten Knoten pro Analyse. Auch das garantiert keine bestimmte Genauigkeit.

Für eine größere Sammlung ist ein kurzer Suchlauf mit anschließender gezielter Nachprüfung häufig zweckmäßiger als ein sehr langer Lauf über alles. Dokumentiere Engine-Version und Einstellungen, wenn du Ergebnisse vergleichen möchtest. Zwei getrennte Suchen können bei engem Rechenbudget leicht unterschiedliche Bewertungen liefern; besonders knappe Treffer nahe der Schwelle verdienen deshalb eine erneute Prüfung.

Wie sieht die neue PGN aus?

Findet das Skript einen Fehler, übernimmt es die Züge davor, fügt den Ersatz-Zug hinzu und beendet die Linie. Das Ergebnisfeld Result wird auf * gesetzt. Das bedeutet hier: Die neue Linie hat kein festgestelltes Partieergebnis. Ein Sieg oder eine Niederlage aus der Originalpartie wäre für diese abweichende Fortsetzung irreführend.

Standardmäßig steht am letzten Zug ein englischer Kommentar. Er enthält den ursprünglich gespielten Zug, den Ersatz-Zug, die beiden Bewertungen aus weißer Sicht und deren Verlustdifferenz. Der Originalzug bleibt dadurch als Text nachvollziehbar, wird aber nicht als alternative Brettvariante bewahrt.

Bei bearbeiteten Partien werden vorhandene Kommentare und Nebenvarianten nicht rekonstruiert. Die Partie-Header werden grundsätzlich kopiert; dadurch können Metadaten wie eine vorhandene ECO-Kennung oder eine Eröffnungsbezeichnung eine zusätzliche Kontrolle brauchen. Die Ausgabedatei ist eine Trainingsableitung, kein Ersatz für dein vollständiges Partiearchiv.

Ohne --keep-unmodified enthält die Ausgabe nur bearbeitete Partien. Eine kleine oder leere Datei kann deshalb schlicht bedeuten, dass im gewählten Bereich keine Treffer vorlagen. Sie bedeutet nicht automatisch, dass das Programm versagt hat – aber auch nicht, dass sämtliche Ausgangspartien fehlerfrei wären.

Ein Beispiel am Brett: die Drohung auf f7 übersehen

Betrachten wir eine einfache Lehrstellung nach 1. e4 e5 2. Lc4 Sc6 3. Dh5. Schwarz ist am Zug. Dame und Läufer richten sich gegen f7. Der scheinbar natürliche Entwicklungszug 3…Sf6?? greift zwar die Dame an, lässt aber 4. Dxf7# zu.

Die Dame schlägt auf f7, wird dort vom Läufer c4 gedeckt und setzt matt. Genau solche konkreten Zusammenhänge sollten am Ende deiner Arbeit stehen: nicht nur „Die Engine mag meinen Zug nicht“, sondern „Ich habe einen Damenangriff beantwortet und dabei die Mattdrohung übersehen“.

Ein Zug wie 3…g6 begegnet der unmittelbaren Mattdrohung und greift die Dame an. Er ist hier als verständliche Lehralternative genannt; welcher Zug vom Cleaner tatsächlich eingesetzt wird, entscheidet die konkrete Stockfish-Analyse. Es wird deshalb keine bestimmte Engine-Ausgabe oder Centipawn-Zahl für dieses Beispiel behauptet.

Damit der Cleaner diesen Fehler überhaupt prüfen kann, muss der Suchbereich den dritten schwarzen Zug einschließen. Ein Lauf mit --start-move 6 würde ihn absichtlich überspringen. Das Beispiel macht deutlich, warum „kein Treffer“ immer im Zusammenhang mit deinen Einstellungen gelesen werden muss.

Vom korrigierten Zug zur brauchbaren Trainingslinie

Der letzte Zug der neuen Linie ist eine Frage an dich: Warum ist dieser Zug besser, und was mache ich nach der nächsten gegnerischen Antwort? Wenn du darauf keine Antwort hast, ist die Datei technisch bearbeitet, dein Repertoire aber noch nicht gefestigt.

• Stellung selbst betrachten: Verdecke den Ersatz-Zug zunächst. Welche Drohung, welcher Abtausch oder welcher Bauernhebel war wichtig?
• Die Korrektur prüfen: Lass die Schlüsselstellung länger analysieren. Bleibt der Vorschlag stabil? Gibt es eine ähnlich gute Alternative, die besser zu deinem Repertoire passt?
• Gegnerische Antworten ergänzen: Untersuche mindestens die naheliegende Antwort und die kritische Herausforderung. Der Cleaner erledigt diesen Schritt nicht automatisch.
• Eine Erklärung notieren: Schreibe einen eigenen Satz zur Idee. Zum Beispiel: „Erst f7 sichern, dann die Dame mit Tempo angreifen.“
• Aktiv wiederholen: Spiele die Linie später ohne Hilfe nach und erkläre den Korrekturpunkt erneut. Prüfe in künftigen Partien, ob du das Problem wiedererkennst.

Zum Nachspielen und Arbeiten mit PGN oder FEN kannst du das spielbare Schachbrett nutzen. Einen Überblick über weitere Werkzeuge bietet die Seite Schach-Tools.

Was der Cleaner nicht leisten kann

Er baut kein vollständiges Repertoire. Fehlende Antworten auf gegnerische Abweichungen bleiben fehlend. Doppelte Linien, Zugumstellungen und ein zusammengeführter Variantenbaum werden nicht automatisch organisiert. Der Code untersucht die Hauptlinie jeder Partie, nicht sämtliche enthaltenen Nebenvarianten.

Er bewertet keine persönliche Spielbarkeit. Stockfish kann eine komplizierte Verteidigung bevorzugen, die du am Brett kaum beherrschst. Eine etwas anders bewertete Alternative kann für dein Training dennoch sinnvoll sein. Behalte sie bewusst, nachdem du ihren Preis und ihre Idee verstanden hast.

Er findet nur den ersten Treffer im gewählten Bereich. Gegnerische Fehler werden dabei nicht korrigiert. Auch wenn deine eigene Farbe keinen großen Verlust verursacht, kann die Linie bereits auf einer schwachen gegnerischen Fortsetzung beruhen. Eine vorbereitete Antwort muss deshalb auch gegen stärkeres Gegenspiel geprüft werden.

Er ist von seiner Analyse abhängig. Ein kurzer Suchlauf ist ein Filter, kein endgültiges Urteil. Mattbewertungen werden intern für den Vergleich auf eine große numerische Skala abgebildet. Entsprechende Kommentarwerte solltest du nicht als normalen materiellen Abstand in Bauerneinheiten interpretieren.

Er erklärt keine Ursachen. Ob du eine Drohung übersehen, eine Struktur falsch eingeschätzt oder einen Zug nur unter Zeitdruck gewählt hast, erfährst du aus deiner eigenen Erinnerung und Analyse. Ein Bewertungsverlust kann beim Priorisieren helfen; die Trainingsaufgabe musst du daraus ableiten.

Große Dateien und typische Stolperstellen

Das Skript verarbeitet Partien nacheinander. Die Option --threads kann Stockfish mehr Rechenthreads geben, macht aus der PGN-Verarbeitung aber keine parallele Analyse mehrerer Partien. Beginne mit einer kleinen Stichprobe und miss deren tatsächliche Laufzeit, bevor du eine riesige Sammlung startest.

Bei UCI-Fehlern oder Zeitüberschreitungen wird eine betroffene Partie als fehlgeschlagene Analyse gezählt; das Skript versucht danach, die Engine neu zu starten. Mit --keep-unmodified kann diese Originalpartie trotzdem in die Ausgabe gelangen. Eine vorhandene Ausgabepartie ist dann ausdrücklich kein Nachweis einer erfolgreich abgeschlossenen Prüfung.

Achte auch auf die Abschlusszahlen: Partien modifiziert zählt gefundene und bearbeitete Fehlstellen. Die technisch beschriftete Zeile Partien mit Fehler zählt im Code dagegen fehlgeschlagene Analysen, nicht Schachfehler auf dem Brett. Das sind zwei unterschiedliche Informationen.

• Die Engine startet nicht: Kontrolliere Dateiname, Pfad und Ausführbarkeit der Stockfish-Datei.
• Es fehlen Treffer: Prüfe Farbe, Startzug, Halbzuggrenze und Schwelle. Stelle sicher, dass du wirklich die zu deinem Repertoire passende Partiensammlung gewählt hast.
• Der Lauf dauert lange: Begrenze zunächst den Suchbereich und verwende ein moderates Rechenbudget.
• Es gibt Timeouts: Passe Suchbudget und Timeout-Einstellung zusammen an; bei einem langen gewünschten Zeitlimit sollte auch die Kommunikation ausreichend Spielraum haben.
• Die Ausgabe ist ungewöhnlich lang: Prüfe, ob –keep-unmodified vollständige Originalpartien übernommen hat.

Häufige Fragen

Kann ich beide Farben gleichzeitig bereinigen?

Pro Aufruf wird eine Farbe gewählt. Für dein Weiß- und Schwarzrepertoire sind zwei getrennte Läufe mit passend gefilterten Eingabedateien sinnvoll. Untersuche nicht einfach alle Züge einer Farbe aus einer gemischten Sammlung, wenn du eigentlich nur deine eigenen Entscheidungen verbessern möchtest.

Kann ich eine kommentierte Repertoire-PGN direkt verwenden?

Technisch lassen sich PGNs einlesen, untersucht wird aber nur ihre Hauptlinie. Bei bearbeiteten Partien werden vorhandene Kommentare und Seitenvarianten nicht übernommen. Nutze daher eine Kopie und übertrage geprüfte Korrekturen anschließend gezielt in deine sorgfältig gepflegte Repertoiredatei.

Ist das Werkzeug kostenlos und lokal nutzbar?

Das Projekt ist unter der GNU GPL v3 veröffentlicht. Die Analyse erfolgt mit deiner lokal gestarteten Engine; im geprüften Python-Skript gibt es keinen Upload der PGN an einen Analysedienst. Für Installation und Downloads benötigst du natürlich Zugriff auf die jeweiligen Bezugsquellen.

Muss ich jeden vorgeschlagenen Zug in mein Repertoire übernehmen?

Nein. Überprüfe wichtige Vorschläge, verstehe die Idee und entscheide dann. Die bereinigte Datei ist ein Arbeitsvorschlag. Dein Repertoire sollte aus Zügen bestehen, die du bewusst gewählt hast und deren typische Folgestellungen du spielen kannst.

Weniger Fehler einüben, mehr Ideen verstehen

Der Repertoire Cleaner ist besonders dann nützlich, wenn deine Partiensammlung wächst und du wiederkehrende Eröffnungsprobleme systematisch herausfiltern möchtest. Er verkürzt die Suche nach kritischen Stellen und stellt dort einen Stockfish-Vorschlag bereit. Genau darin liegt sein praktischer Wert.

Der nächste Schritt gehört dir: Vorschlag überprüfen, gegnerische Antworten ergänzen, die Idee erklären und die Linie wiederholen. So wird aus einer Sammlung alter Partien eine Vorbereitung, die dir am Brett tatsächlich hilft. Viel Spaß beim Ausprobieren und gut Holz!

Quellen und technischer Stand

Grundlage dieses Beitrags sind die Projektbeschreibung, der Python-Quellcode und die Paketanforderungen, abgerufen am 30. September 2026. Parameter und Ausgabeverhalten beziehen sich auf diesen Stand. Die Befehle sind nachvollziehbare Anwendungsbeispiele; es werden keine eigenen Laufzeitmessungen oder Engine-Testergebnisse behauptet.