PGN File Documentation

---

Technical details

Feature	Value
Full name	Portable Game Notation (chess)
File extension	.pgn
MIME type	application/x-chess-pgn
Format type	Plain-text game record (tag pairs + movetext)
Developer	Steven J. Edwards (community specification)
Introduced	1994
Encoding	ASCII / ISO 8859-1 text (UTF-8 in modern use)
Move notation	Standard Algebraic Notation (SAN)
Header	Seven Tag Roster: Event, Site, Date, Round, White, Black, Result
Comments	{ ... } braces; ; to end of line
Variations	( ... ) parentheses, may nest
Annotations	Numeric Annotation Glyphs $0–$255
Result markers	1-0, 0-1, 1/2-1/2, *
Magic number	None; files typically begin [Event "
Open standard	Yes — open, freely published specification
Games per file	One or many (a “database” of concatenated games)
Related extensions	.fen, .epd, .si4, .cbh
Specification	PGN Standard (Edwards, 1994)

What is a PGN file?

PGN stands for Portable Game Notation. It is the standard plain-text format for recording chess games, designed by Steven J. Edwards and published in 1994 with the explicit goal of being readable by both people and programs. A .pgn file is ordinary text: open it in Notepad and you see the moves. Open it in a chess program and those same characters are played out on a board, with engine analysis and branching variations. One file can hold a single game or a database of thousands concatenated one after another.

The design is deliberately conservative. PGN uses only printable ASCII, encodes moves in the same Standard Algebraic Notation a player would write on a scoresheet, and separates a machine-readable header from the moves. That is why a PGN exported from Lichess in 2026 opens in a chess program written decades earlier, and why the format became the universal interchange between engines, databases and websites. The rest of this article covers the two sections of a game, the move syntax, and the annotation layers.

The tag-pair section and the Seven Tag Roster

A game begins with a tag-pair section: a run of header lines, each a single tag pair. The syntax is a left bracket, a tag name, a space, the value in double quotes, and a right bracket.

[Event "F/S Return Match"]
[Site "Belgrade, Serbia JUG"]
[Date "1992.11.04"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1-0"]

Those seven tags, in that exact order, are the Seven Tag Roster (STR), and the specification requires them, in this sequence, before any other tag, for a game in archival “export” format. Each carries a defined meaning: Event and Site name the competition and place, Date uses YYYY.MM.DD with a literal ? for any unknown field, Round is the round number, White and Black give the players as Last, First, and Result repeats the game outcome. Beyond the roster, optional tags are common: WhiteElo, BlackElo, ECO (opening code), FEN (a starting position other than the initial one), TimeControl and Termination. A tag name is a single token of letters, digits and underscores; values are quoted strings, with the backslash escaping an embedded quote or backslash.

The movetext section: Standard Algebraic Notation

A blank line separates the tags from the movetext section, which lists the moves. Each full move is a number, a period, White’s move, then Black’s move; whitespace and line breaks between tokens are not significant, so a parser tokenises freely.

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 4. Ba4 Nf6 5. O-O Be7
6. Re1 b5 7. Bb3 d6 8. c3 O-O 9. h3 Nb8 10. d4 Nbd7 1-0

Moves use Standard Algebraic Notation (SAN), the same notation printed in chess books. A move names the moving piece by an uppercase letter (K, Q, R, B, N; pawns have no letter) followed by the destination square. A capture inserts x, so Bxe5 is a bishop taking on e5 and exd5 is a pawn capture from the e-file. When two identical pieces could reach the same square, a disambiguation file or rank is inserted, as in Nbd7 or R1e2. Castling is O-O kingside and O-O-O queenside (letter O, not zero). A pawn reaching the last rank promotes with = and a piece letter, as in e8=Q. Suffix symbols mark the position: + for check and # for checkmate. A SAN move is therefore as short as two characters (d4) and as long as seven (Qa6xb7#, fxg1=Q+).

Game-termination markers

Every game ends with a termination marker, one of four tokens, and this same token must equal the Result tag in the header. 1-0 is a White win, 0-1 a Black win, 1/2-1/2 a draw, and * an unfinished or unknown result (an adjourned or ongoing game). The marker is what lets a parser know one game has finished when many are concatenated: after the result token, the next left bracket at the start of a line begins the next game’s tag section. Because the marker is mandatory, a file of a thousand games is unambiguously splittable without any separator character or length prefix.

Comments, variations and Numeric Annotation Glyphs

PGN carries three layers of analysis on top of the bare moves. Comments come in two forms: text inside { ... } braces, which may span lines, and a ; that comments to the end of the current line. Recursive variations are alternative lines wrapped in ( ... ) parentheses, inserted right after the move they replace, and they may nest to any depth, which is how annotated games show “instead of this, better was…” branches.

4. Ba4 Nf6 5. O-O Be7 {The Closed Ruy Lopez.}
   ( 5... Nxe4 6. d4 b5 {the Open Variation} )
6. Re1 b5 $1 7. Bb3 O-O $14

The third layer is the Numeric Annotation Glyph (NAG): a dollar sign followed by an integer from 0 to 255, encoding a standard evaluation symbol. $1 is a good move (the ! a commentator would write), $2 a mistake (?), $4 a blunder (??), and codes in the teens describe the position ($14 = White is slightly better). Encoding these as numbers instead of Unicode symbols kept the whole format inside plain ASCII, so a NAG survives any text transport. Many programs also accept the raw !, ?, !? suffixes directly and convert them to NAGs on import.

Import format versus export format

The specification distinguishes two profiles of the same syntax. Import format is lenient: it is what a parser must accept from humans and other tools, tolerating extra whitespace, blank lines, tab characters, moves broken across lines and result markers on their own line. Export format is strict and canonical: it is what a program should write, so that files compare cleanly and diff sensibly. Export format fixes the tag order (Seven Tag Roster first), uses exactly one space between tokens, wraps movetext at 80 columns without splitting a token across the wrap, and places no space inside a move number. Two programs that both emit export format produce byte-comparable files for the same game, which is what makes PGN a dependable archival and version-control format.

PGN versus FEN and EPD: whole games versus single positions

PGN records a game, the full sequence of moves from a starting position. When you only need one position, the companion text format is FEN (Forsyth–Edwards Notation), a single line that encodes the piece placement rank by rank, whose turn it is, castling rights, the en-passant target square, and the halfmove and fullmove counters. A PGN game can begin from a non-standard position by carrying that FEN string in a [FEN "..."] header together with [SetUp "1"]. EPD (Extended Position Description) builds on FEN by attaching named operations (a best move, an identifier, an evaluation) to a position, which is how engine test suites are distributed. In a chess GUI you get a FEN for any position by navigating to it and copying it; that is a per-position export, not a conversion of the whole PGN, because the game and the single frozen position are simply different objects.

Frequently asked questions

Can I open a PGN in a plain text editor?

Yes. A PGN is ASCII text, so Notepad, TextEdit or any editor shows the header tags and the moves exactly as stored. You just will not see the game on a board or get analysis; for that, paste the text into Lichess or Chess.com, or open it in a desktop program such as SCID vs. PC. Renaming .pgn to .txt is therefore not a conversion, it is the same bytes under a different name.

How does one file hold many games?

Games are simply concatenated. Each game’s mandatory result marker (1-0, 0-1, 1/2-1/2 or *) ends its movetext, and the next line beginning with [Event " starts the following game’s header. A parser splits the file on that pattern, which is why grandmaster databases ship as a single large .pgn.

Why is a move sometimes written Nbd7 instead of Nd7?

Because two knights could legally move to d7, so SAN disambiguates by adding the file (b) of the knight that actually moved. If the file alone is not enough, the rank is used, and if neither is, both are given. The rule keeps every move unambiguous without stating the origin square in full.

References

• PGN Standard — full specification (Steven J. Edwards, 1994)
• Lichess — paste / import a PGN to replay and analyse
• SCID vs. PC — open-source chess database

Feedback

Was this page helpful?

Yes No

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.