Portable Game Notation

Filename extension	.pgn
Internet media type	application/vnd.chess-pgn
Developed by	Steven J. Edwards
Initial release	1993 (1993)
Type of format	Chess game record

Portable Game Notation (PGN) is a standard plain text format for recording chess games (both the moves and related data), which can be read by humans and is also supported by most chess software.

History

PGN was devised around 1993, by Steven J. Edwards, and was first popularized and specified via the Usenet newsgroup rec.games.chess.

Usage

PGN is structured "for easy reading and writing by human users and for easy parsing and generation by computer programs." The chess moves themselves are given in algebraic chess notation using English initials for the pieces. The filename extension is .pgn.

There are two formats in the PGN specification, the "import" format and the "export" format. The import format describes data that may have been prepared by hand, and is intentionally lax; a program that can read PGN data should be able to handle the somewhat lax import format. The export format is rather strict and describes data prepared under program control, similar to a pretty printed source program reformatted by a compiler. The export format representations generated by different programs on the same computer should be exactly equivalent, byte for byte.

PGN text begins with a set of "tag pairs" (a tag name and its value), followed by the "movetext" (chess moves with optional commentary).

Tag pairs

Tag pairs begin with an initial left bracket [, followed by the name of the tag in plain ASCII text. The tag value is enclosed in double-quotes, and the tag is then terminated with a closing right bracket ]. A quote inside a tag value is represented by the backslash immediately followed by a quote. A backslash inside a tag value is represented by two adjacent backslashes. There are no special control codes involving escape characters, or carriage returns, and linefeeds to separate the fields, and superfluous embedded spaces are usually skipped when parsing.

Seven Tag Roster

PGN data for archival storage is required to provide seven tag pairs – together known as the "Seven Tag Roster". In export format, these tag pairs must appear before any other tag pairs and in this order:

Event	Name of the tournament or match event.
Site	Location of the event. This is in City, Region COUNTRY format, where COUNTRY is the three-letter International Olympic Committee code for the country. An example is New York City, NY USA. Although not part of the specification, some online chess platforms will include a URL or website as the site value.
Date	Starting date of the game, in YYYY.MM.DD form. ?? is used for unknown values.
Round	Playing round ordinal of the game within the event.
White	Player of the white pieces, in Lastname, Firstname format.
Black	Player of the black pieces, same format as White.
Result	Result of the game. It is recorded as White score, dash, then Black score, or * (other, e.g., the game is ongoing).

Optional tag pairs

The standard allows for other optional tag pairs. The more common ones include:

Annotator	The person providing notes to the game.
PlyCount	String value denoting the total number of half-moves played.
TimeControl	e.g. 40/7200:3600 (moves per seconds: sudden death seconds)
Time	Time the game started, in HH:MM:SS format, in local clock time.
Termination	Gives more details about the termination of the game. It may be abandoned, adjudication (result determined by third-party adjudication), death, emergency, normal, rules infraction, time forfeit, or unterminated.
Mode	OTB (over-the-board) ICS (Internet Chess Server)
FEN	The initial position of the chessboard, in Forsyth–Edwards Notation. This is used to record partial games (starting at some initial position). It is also necessary for chess variants such as Chess960, where the initial position is not always the same as traditional chess. If a FEN tag is used, a separate tag pair SetUp must also appear and have its value set to 1.

Movetext

Chessboard notation

The movetext describes the actual moves of the game. This includes move number indicators (numbers followed by either one or three periods; one if the next move is White's move, three if the next move is Black's move) and movetext in Standard Algebraic Notation (SAN).

For most moves the SAN consists of the letter abbreviation for the piece, an x if there is a capture, and the two-character algebraic name of the final square the piece moved to. The letter abbreviations are K (king), Q (queen), R (rook), B (bishop), and N (knight). The pawn is given an empty abbreviation in SAN movetext, but in other contexts the abbreviation P is used. The algebraic name of any square is as per usual algebraic chess notation; from white's perspective, the leftmost square closest to white is a1, the rightmost square closest to the white is h1, and the rightmost (from white's perspective) square closest to black side is h8.

In a few cases, a more detailed representation is needed to resolve ambiguity; if so, the piece's file letter, numerical rank, or the exact square is inserted after the moving piece's name (in that order of preference). Thus, Nge2 specifies that the knight originally on the g-file moves to e2.

SAN kingside castling is indicated by the sequence O-O; queenside castling is indicated by the sequence O-O-O (note that these are capital Os, not zeroes, contrary to the FIDE standard for notation). Pawn promotions are notated by appending = to the destination square, followed by the piece the pawn is promoted to. For example: e8=Q. If the move is a checking move, + is also appended; if the move is a checkmating move, # is appended instead. For example: e8=Q#.

An annotator who wishes to suggest alternative moves to those actually played in the game may insert variations enclosed in parentheses. They may also comment on the game by inserting Numeric Annotation Glyphs (NAGs) into the movetext. Each NAG reflects a subjective impression of the move preceding the NAG or of the resultant position.

If the game result is anything other than *, the result is repeated at the end of the movetext.

Comments

Comments are inserted by either a ; (a comment that continues to the end of the line) or a { (which continues until a }). Comments do not nest.

Example

Here is the PGN format of the 29th game of the 1992 match played in Yugoslavia between Bobby Fischer and Boris Spassky:

[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/2-1/2"]

1.e4 e5 2.Nf3 Nc6 3.Bb5 {This opening is called the Ruy Lopez.} 3...a6
4.Ba4 Nf6 5.O-O Be7 6.Re1 b5 7.Bb3 d6 8.c3 O-O 9.h3 Nb8 10.d4 Nbd7
11.c4 c6 12.cxb5 axb5 13.Nc3 Bb7 14.Bg5 b4 15.Nb1 h6 16.Bh4 c5 17.dxe5
Nxe4 18.Bxe7 Qxe7 19.exd6 Qf6 20.Nbd2 Nxd6 21.Nc4 Nxc4 22.Bxc4 Nb6
23.Ne5 Rae8 24.Bxf7+ Rxf7 25.Nxf7 Rxe1+ 26.Qxe1 Kxf7 27.Qe3 Qg5 28.Qxg5
hxg5 29.b3 Ke6 30.a3 Kd6 31.axb4 cxb4 32.Ra5 Nd5 33.f3 Bc8 34.Kf2 Bf5
35.Ra7 g6 36.Ra6+ Kc5 37.Ke1 Nf4 38.g3 Nxh3 39.Kd2 Kb5 40.Rd6 Kc5 41.Ra6
Nf2 42.g4 Bd3 43.Re6 1/2-1/2

Handling chess variants

Many chess variants can be recorded using PGN, provided the names of the pieces can be limited to one character, usually a letter and not a number. They are typically noted with a tag named "Variant" giving the name of the rules. The term "Variation" must be avoided, as that refers to the name of an opening variation. Note that traditional chess programs can only handle, at most, a few variants. Forsyth-Edwards Notation is used to record the starting position for variants (such as Chess960) which have initial positions other than the orthodox chess initial position.

Blind Game Notation

A proposed variant of pgn is Blind Game Notation, or BGN, for Blind Players. FIDE Master Kevin Bachler developed this variant in 2022 in conjunction with several members of the US Blind Chess Association, notably Marilyn Bland and Eric (Ché) Martin. The key differences are

1. Translation for Output: For any existing database system, specialized chess symbols other than the basic are translated to text, because the more complex symbols are not available within a simple ASCII character set. The basic symbols are:

    a. !! - Excellent move
    b. !  - Good move
    c. !? - Double-edged move
    d. ?! - Dubious move
    e. ?  - Bad move
    f. ?? - Blunder
    g. +  - Check
    h. #  - Checkmate

For example, the chess symbol ∆ means “with the idea of.” Because this symbol is not generally available, it should always be converted to text when saved to BGN or printed from BGN.

2. Line Breaks and Game Moves: Text or screen readers used by blind players often have issues with verbalizing "run-on" text understandable. Thus, the following rules are important to make reading to the blind player more understandable.

a. Paired game moves appear on separate lines. (Scoresheet fashion.)

   Example: Do not use 1. e4 e5 2. Nf3 Nc6 but instead
   1. e4 e5
   2. Nf3 Nc6

b. A blank line must appear after a move and before a comment.

c. Comments begin on a new line, with the mentioned blank line above it and below the move to which the comment applies.

d. A Comment's beginning is denoted by a single vertical bar sign plus a space before the comment begins

e. The end of a Comment is on a separate line after the end of the comment text. This line has 2 vertical bars plus a space.

Example of the above comments: Example:

  1. e4 e5
  2. Nf3 Nc6
  3. Bb5
  
  | White opens with the Ruy Lopez Opening. 
  || 
  
  3...  a6

f. Vertical bars are important because text or screen readers often only announce whatever sort of bracket PGN software provides only by the user exploring with the cursor, which is tedious for the blind player. With this revised format, one can use the arrow down key to find when a vertical bar is announced, indicating a comment has begun. Double vertical bars indicating the closure of the comment are on a separate line, so anyone wishing to skip the comment can arrow down the line by line until they are announced.

3. Comments must never begin with a move, as this is too easily mistaken for normal notation. When a move is to start a comment, start like this: | Comment:

4. Start each sentence of a comment on a separate line.

5. For variations: Start it on a new line with a letter:

Example:

|A. 6 Ng5 Bg7
||
|B. 6 d3 d6
||

For nested variations, add numbers. Extended text sounds like spaghetti to the blind player.

Example

|A 6 Ng5 Bg7
| Comment: A1 7 d3 d6 8 Bf4 00
||
| Comment: A2 7 a3 d6 8 h3 Nd7
||

Numeric Annotation Glyphs

Numeric Annotation Glyphs or NAGs are used to annotate chess games when using a computer, typically providing an assessment of a chess move or a chess position. NAGs exist to indicate a simple annotation in a language independent manner. NAGs were first formally documented in 1994 by Steven J. Edwards in his "Portable Game Notation Specification and Implementation Guide". Within the PGN specification, 256 NAGs are proposed of which the first 140 are defined; the remainder were reserved for future definition.

A Numeric Annotation Glyph is composed of a dollar sign character ("$") immediately followed by one or more digit characters. Each NAG then has a specific meaning and often a standard typographical representation. The meanings first defined stemmed from the use of specific typographic symbols when annotators were commenting upon chess games; most especially in Chess Informant publications. The objective was to devise an alternative representation of these symbols which could be incorporated in the simple computer file format proposed as the PGN standard. This mechanism allowed often sophisticated typography to be expressed using the simple ASCII character set.

Since its inception there has been no attempt to further formalise or standardise the meaning of the undefined 116 NAGs although PGN editors, such as ChessPad, have variously used these higher glyphs.

NAG Groupings

NAG range	Classification
$0	provided for the convenience of software designers as a placeholder value; should not appear in PGN files and has no typographic representation
$1-$9	Move assessments
$10-$135	Positional Assessments
$136-$139	Time Pressure Commentaries
$140+	not defined

Standard NAGs

NAG	Meaning	Symbol	Unicode	HTML	Name
$0	null annotation
$1	good move (traditional "!") see also Nunn Convention for alternate meanings	!	U+0021	!	single exclamation mark
$2	poor move or mistake (traditional "?") (and Nunn Convention)	?	U+003F	?	single question mark
$3	very good or brilliant move (traditional "!!") (and Nunn Convention)	‼	U+203C		double exclamation mark
$4	very poor move or blunder (traditional "??") (and Nunn Convention)	⁇	U+2047		double question mark
$5	speculative or interesting move (traditional "!?") (and Nunn Convention)	⁉	U+2049		exclamation question mark
$6	questionable or dubious move (traditional "?!") (and Nunn Convention)	⁈	U+2048		question mark and exclamation mark
$7	forced move (all others lose quickly) or only move	□	U+25A1	□	white square
$8	singular move (no reasonable alternatives)
$9	worst move
$10	drawish position or even	=	U+003D	=	equal sign
$11	equal chances, quiet position
$12	equal chances, active position
$13	unclear position	∞	U+221E	∞	infinity
$14	White has a slight advantage	⩲	U+2A72	⩲	plus sign above equals sign
$15	Black has a slight advantage	⩱	U+2A71	⩱	equals sign above plus sign
$16	White has a moderate advantage	±	U+00B1	±	plus-minus sign
$17	Black has a moderate advantage	∓	U+2213	∓	minus-or-plus sign
$18	White has a decisive advantage	+ −	U+002B U+002D	+ -	plus sign, hyphen-minus sign
$19	Black has a decisive advantage	− +	U+002D U+002B	- +	hyphen-minus sign, plus sign
$20	White has a crushing advantage (Black should resign)
$21	Black has a crushing advantage (White should resign)
$22	White is in zugzwang	⨀	U+2A00	⨀	N-ary circled dot operator
$23	Black is in zugzwang
$24	White has a slight space advantage
$25	Black has a slight space advantage
$26	White has a moderate space advantage	○	U+25CB	○	White circle
$27	Black has a moderate space advantage
$28	White has a decisive space advantage
$29	Black has a decisive space advantage
$30	White has a slight time (development) advantage
$31	Black has a slight time (development) advantage
$32	White has a moderate time (development) advantage	⟳	U+27F3		clockwise gapped circle arrow
$33	Black has a moderate time (development) advantage
$34	White has a decisive time (development) advantage
$35	Black has a decisive time (development) advantage
$36	White has the initiative	↑	U+2191	↑	upwards arrow
$37	Black has the initiative
$38	White has a lasting initiative
$39	Black has a lasting initiative
$40	White has the attack	→	U+2192	→	rightwards arrow
$41	Black has the attack
$42	White has insufficient compensation for material deficit
$43	Black has insufficient compensation for material deficit
$44	White has sufficient compensation for material deficit	⯹	U+2BF9	⯹	equals sign with infinity below
$45	Black has sufficient compensation for material deficit
$46	White has more than adequate compensation for material deficit
$47	Black has more than adequate compensation for material deficit
$48	White has a slight center control advantage
$49	Black has a slight center control advantage
$50	White has a moderate center control advantage
$51	Black has a moderate center control advantage
$52	White has a decisive center control advantage
$53	Black has a decisive center control advantage
$54	White has a slight kingside control advantage
$55	Black has a slight kingside control advantage
$56	White has a moderate kingside control advantage
$57	Black has a moderate kingside control advantage
$58	White has a decisive kingside control advantage
$59	Black has a decisive kingside control advantage
$60	White has a slight queenside control advantage
$61	Black has a slight queenside control advantage
$62	White has a moderate queenside control advantage
$63	Black has a moderate queenside control advantage
$64	White has a decisive queenside control advantage
$65	Black has a decisive queenside control advantage
$66	White has a vulnerable first rank
$67	Black has a vulnerable first rank
$68	White has a well protected first rank
$69	Black has a well protected first rank
$70	White has a poorly protected king
$71	Black has a poorly protected king
$72	White has a well protected king
$73	Black has a well protected king
$74	White has a poorly placed king
$75	Black has a poorly placed king
$76	White has a well placed king
$77	Black has a well placed king
$78	White has a very weak pawn structure
$79	Black has a very weak pawn structure
$80	White has a moderately weak pawn structure
$81	Black has a moderately weak pawn structure
$82	White has a moderately strong pawn structure
$83	Black has a moderately strong pawn structure
$84	White has a very strong pawn structure
$85	Black has a very strong pawn structure
$86	White has poor knight placement
$87	Black has poor knight placement
$88	White has good knight placement
$89	Black has good knight placement
$90	White has poor bishop placement
$91	Black has poor bishop placement
$92	White has good bishop placement
$93	Black has good bishop placement
$94	White has poor rook placement
$95	Black has poor rook placement
$96	White has good rook placement
$97	Black has good rook placement
$98	White has poor queen placement
$99	Black has poor queen placement
$100	White has good queen placement
$101	Black has good queen placement
$102	White has poor piece coordination
$103	Black has poor piece coordination
$104	White has good piece coordination
$105	Black has good piece coordination
$106	White has played the opening very poorly
$107	Black has played the opening very poorly
$108	White has played the opening poorly
$109	Black has played the opening poorly
$110	White has played the opening well
$111	Black has played the opening well
$112	White has played the opening very well
$113	Black has played the opening very well
$114	White has played the middlegame very poorly
$115	Black has played the middlegame very poorly
$116	White has played the middlegame poorly
$117	Black has played the middlegame poorly
$118	White has played the middlegame well
$119	Black has played the middlegame well
$120	White has played the middlegame very well
$121	Black has played the middlegame very well
$122	White has played the ending very poorly
$123	Black has played the ending very poorly
$124	White has played the ending poorly
$125	Black has played the ending poorly
$126	White has played the ending well
$127	Black has played the ending well
$128	White has played the ending very well
$129	Black has played the ending very well
$130	White has slight counterplay
$131	Black has slight counterplay
$132	White has moderate counterplay	⇆	U+21C6	⇆	leftwards arrow over rightwards arrow
$133	Black has moderate counterplay
$134	White has decisive counterplay
$135	Black has decisive counterplay
$136	White has moderate time control pressure
$137	Black has moderate time control pressure
$138	White has severe time control pressure / zeitnot	⨁	U+2A01	⨁	n-ary circle plus operator
$139	Black has severe time control pressure / zeitnot

Non-standard NAGs

NAG	Used by	Meaning	Symbol	Unicode	HTML	Name
$140	ChessPad	With the idea...	∆	U+2206		increment
$141	ChessPad	Aimed against...	∇	U+2207		nabla
$142	ChessPad	Better is...	⌓	U+2313	⌓	segment
$143	ChessPad	Worse is...	<=			less than, equal to
$144	ChessPad	Equivalent is...	==			equal to, equal to
$145	ChessPad	Editorial comment	RR			capital R, capital R
$146	ChessPad	Novelty	N			capital N
$147–$219		Not defined
$220	ChessPad	Diagram	⬒ (UI only)
$221	ChessPad	Diagram (from Black)	⬓ (UI only)
$222–$237		Not defined
$238	ChessPad	Space advantage	○	U+25CB	&cir;	white circle
$239	ChessPad	File (columns on the chessboard labeled a-h)	⇔	U+21D4	&hArr;	left right double arrow
$240	ChessPad	Diagonal	⇗	U+21D7	&neArr;	north east double arrow
$241	ChessPad	Centre	⊞	U+229E	&boxplus;	squared plus
$242	ChessPad	King-side	⟫	U+27EB	&Rang;	right double angle bracket
$243	ChessPad	Queen-side	⟪	U+27EA	&Lang;	left double angle bracket
$244	ChessPad	Weak point	✕	U+2715		multiplication x
$245	ChessPad	Ending	⊥	U+22A5	&perp;	up tack
$246	ChessPad	Bishop pair	CA Chess font: white square with white square to northeast
$247	ChessPad	Opposite Bishops	CA Chess font: white square with black square to northeast
$248	ChessPad	Same Bishops	CA Chess font: black square with black square to northeast
$249	ChessPad	Connected pawns	⯺	U+2BFA	&#x2bfa;	united symbol
$250	ChessPad	Isolated pawns	⯻	U+2BFB	&#x2bfb;	separated symbol
$251	ChessPad	Doubled pawns	⯼	U+2BFC	&#x2bfc;	doubled symbol
$252	ChessPad	Passed pawn	⯽	U+2BFD	&#x2bfd;	passed symbol
$253	ChessPad	Pawn majority	text
$254	ChessPad	With	∟	U+221F	&#x221f;	right angle
$255	ChessPad	Without	⯾	U+2BFE	&#x2bfe;	reversed right angle

Notes on tables

1. Some of the symbols are not rendered by some browsers
2. The more exotic symbols used by Chess Informator are often derived from common mathematical typographic symbols; their mathematical meaning rarely has any relevance to their chess meaning
3. The entries in the Unicode column are, respectively, the decimal and hexadecimal reference for the character or symbol
4. The entries in the HTML column are named HTML entities for representing the symbol or character; the Unicode numeric value can always be used where a specific entity does not exist. For example, the left right double arrow ($239) can be represented as either Unicode decimal ⇔ (⇔) or Unicode hexadecimal ⇔ (⇔) or HTML ⇔ (⇔). Unless explicitly noted, the Unicode representation can be interpreted as a default.

See also

• Forsyth–Edwards Notation
• X-FEN
• Smart Game Format – Format for recording Go games
• Portable Draughts Notation

Sources

• Krogius, N; Livsic, A; Parma, B; Tajmanov, M. Encyclopedia of Chess Middlegames. (1980) Belgrade: Chess Informant. ISBN 0-7134-3474-0
• Malanovic, Aleksander (Editor) Encyclopedia of Chess Openings, volumes A-E. (1978) Belgrade: Chess Informant. ISBN 0-7134-1044-2