Sudoku File Formats Every Developer Should Know

Why Sudoku file formats matter

A Sudoku is just a 9 by 9 grid of digits and blanks, yet there is no single universal way to store one. Different apps, solvers, and puzzle databases each picked their own convention, so Sudoku file formats are really a small family of text encodings. Understanding them lets you import puzzles from one tool, feed them to your own solver, and export results without corrupting anything. The good news is that almost every format maps cleanly onto the same underlying 9 by 9 array, so a single robust parser can handle most of them.

The 81-character string

The most widespread of all Sudoku file formats is the plain 81-character string. You read the grid left to right and top to bottom, writing one symbol per cell, which gives 81 symbols on a single line. Givens use the digits 1 through 9, and empty cells use either 0 or a period. Because it is one line with no separators, it is trivial to store thousands of puzzles in a text file, one per line, and to paste a single puzzle into a chat or a URL. Many public collections, including large sets of minimal puzzles, ship in exactly this form.

Grid text and simple layouts

Human-friendly formats spread the grid across nine lines of nine characters, which is easier to eyeball. Some add spaces or bars between the three-cell boxes, and dashes between the three-row bands, to draw the classic 3 by 3 structure. Simple Sudoku uses a layout like this, with periods for blanks and separator characters for the boxes. When you parse these, the trick is to ignore anything that is not a digit or a blank marker, then read the remaining cells in order.

The .sdk and .sdm formats

SadMan Sudoku popularized the .sdk format, which stores one puzzle plus optional metadata. Header lines begin with a hash symbol and carry fields such as author, description, comment, date, and difficulty level, followed by nine grid rows using periods for empty cells. The related .sdm format is deliberately minimal: it packs many puzzles into a file, one 81-digit line each, with zeros for blanks. Think of .sdm as a bulk container and .sdk as a single annotated puzzle.

JSON and modern editor formats

Variant Sudoku editors moved to JSON because they need to store far more than digits. A JSON puzzle file typically lists cells, which values are given, cell colors, and any extra rules such as diagonals, thermometers, or killer cages. Editors like the popular web builders often base64-encode this JSON and stuff it into a shareable link. For plain classic Sudoku you rarely need this, but if you support variants, a structured format is the only sane option.

Writing a robust parser

• Strip comment lines and any separator characters before reading cells.
• Accept both 0 and a period as the empty-cell marker.
• Collect only the 81 cell symbols in reading order and ignore the rest.
• Fail loudly if you do not end up with exactly 81 cells.
• Map the symbols to a 9 by 9 array of integers, using 0 for blanks.

A tiny parsing recipe

1. Read the whole file and remove comments and separators.
2. Keep only digits and blank markers, preserving order.
3. Replace each 0 or period with your internal blank value.
4. Verify the count is exactly 81, otherwise reject the input.
5. Reshape the flat list into nine rows of nine cells.

Once your parser understands these Sudoku file formats, you can pull puzzles from anywhere and treat them uniformly. That is exactly how the tools at shapedoku.com stay flexible: internally every shape maps to a digit from 1 to 9, so a shape puzzle and a number puzzle share the same storage and the same parser. If you would rather play than parse, the daily grids at app.shapedoku.com are ready without a single line of code.