A fast, lightweight F# command-line tool to merge multiple PGN (Portable Game Notation) chess game files into a single file.
PGN Merger takes a directory of chess game files and combines them into one consolidated merge.pgn. Perfect for building chess databases from Lichess Elite games, tournament archives, or personal game collections.
PGN (Portable Game Notation) is the standard file format for recording chess games. Each .pgn file contains one or more chess games with metadata headers and move history. Chess players, coaches, and analysts frequently need to merge PGN files into a single database for training, opening preparation, or statistical analysis.
- Merge all PGN files in a directory into one
merge.pgn - Custom output path via
--output - Recursive search through subdirectories via
--recursive - Preserves original file encoding (UTF-8)
- Zero dependencies — standalone CLI binary
- Cross-platform — runs on Windows, macOS, and Linux via .NET
- Progress feedback with throughput stats in verbose mode
- Quiet mode for silent operation
- Error handling for missing directories, empty folders, and permission issues
Grab the latest release for your platform from the Releases page:
| Platform | Asset |
|---|---|
| Linux (x64) | PgnMerger-linux-x64 |
| Windows (x64) | PgnMerger-win-x64.exe |
| macOS (Intel) | PgnMerger-osx-x64 |
| macOS (Apple Silicon) | PgnMerger-osx-arm64 |
No runtime required — self-contained executables.
Requires .NET 10.0 SDK or later:
dotnet tool install -g PgnMergergit clone https://github.com/CorentinGS/pgn-merger.git
cd pgn-merger
dotnet build
dotnet run -- <folder_path> [options]git clone https://github.com/CorentinGS/pgn-merger.git
cd pgn-merger
dotnet build
dotnet run -- <folder_path> [options]dotnet tool install -g PgnMergerPgnMerger <folder_path> [options]| Option | Description |
|---|---|
--output <path> |
Output file path (default: <folder>/merge.pgn) |
--recursive |
Search subdirectories for PGN files |
--verbose |
Show detailed progress with throughput |
--quiet |
Only show errors |
-h, --help |
Show usage information |
Merge all PGN files in a directory:
PgnMerger ./lichess_gamesMerge with custom output file:
PgnMerger ./lichess_games --output ./combined_games.pgnRecursive merge with verbose output:
PgnMerger ./chess_databases --recursive --verbose --output ./all_games.pgnQuiet mode (errors only):
PgnMerger ./games --quiet --output ./merged.pgn| Tool | Language | Standalone | Preserves Headers | Preserves Comments | Merge Type |
|---|---|---|---|---|---|
| PGN Merger (this) | F# / .NET | ✅ Yes | ✅ Yes | ✅ Yes | Concatenation |
| merge-pgn | Python | ❌ Requires python-chess | ❌ No | ❌ No | Variation tree |
| pgn-tools | Python | ❌ Requires python-chess | ✅ Yes | ✅ Yes | Variation tree |
Choose PGN Merger when you want a simple, fast tool to combine PGN databases without extra dependencies or complex merging logic.
Download your Lichess games in PGN format, place them in one folder, and run:
PgnMerger ./my_lichess_gamesThe tool outputs a single merge.pgn with all games combined.
Yes. Export your Chess.com games as PGN, place them in a directory, and run the merger.
Merging (what this tool does) concatenates multiple games into one file. Combining into a single game tree is a different operation; for that, use tools like pgn-tools.
No. PGN Merger concatenates files as-is, preserving all headers, comments, and move text.
- Input: A directory containing one or more
.pgnfiles - Output: A single
merge.pgnfile in the same directory with all games concatenated
The application handles common issues:
- Directory doesn't exist
- No PGN files found in the directory
- File access permission issues
- I/O errors during file operations
- awesome-chess — Curated list of chess resources
- awesome-fsharp — F# ecosystem tools
- python-chess — Python chess library
- Lichess — Free online chess platform
- PGN Standard — PGN specification reference
This project is licensed under the MIT License.