SudokuGen : A Sudoku Generator and Solver for C# and JavaScript

Create and solve sudoku puzzles in your own code, or play them right in your browser.

SudokuGen is our sudoku library: ready-made code that programmers add to their own apps and games. It creates sudoku puzzles that each have exactly one solution, and it solves puzzles too. It comes as a C# library, a command-line app and a JavaScript library, and it is free and open source under the MIT License.

A sudoku game needs puzzles, and a proper puzzle has only one solution. A list of ready-made puzzles runs out sooner or later, so SudokuGen makes a new one whenever you ask. We use it in our own game, Shaolin Sudoku, and in a free web app on this site, and we publish it so you can use it in your own projects.

The web app

We built a free web app with the JavaScript library, so anyone can try SudokuGen without writing any code.

Play in your browser

Create: set the size with the Rank slider (rank 3 is the classic 9×9) and the number of blank squares with the Blanks slider. Type a seed to get the same puzzle again with the same Rank and Blanks, or leave it empty for a random one. The app shows the seed of every puzzle it creates.
Play: fill in squares with the keypad or your keyboard, turn on Notes for pencil marks, and Erase what you don't need. Numbers that repeat in a row, column or box are marked as you go, and the app tells you when the puzzle is solved.
Solve and Restart: Solve fills in the solution when you want to see it, and Restart takes the board back to the start.
Share: the Share button shares a link to your puzzle, with its seed when the app knows it. The puzzle code sits next to it, ready to copy.
Import: paste a link or a puzzle code, including a code from Shaolin Sudoku, and the app checks that the puzzle has exactly one solution.
Auto save: the app keeps your game in your browser, so you can close the tab and carry on later.
Big puzzles: 16×16 and 25×25 puzzles are created, and imported ones checked, in the background, so the page stays responsive while you wait.

Features

Four sizes: the rank is the size of a box, so rank 3 has 3×3 boxes in a 9×9 grid. SudokuGen makes rank 2 (4×4), rank 3 (9×9), rank 4 (16×16) and rank 5 (25×25) puzzles.
One solution: every puzzle it creates has exactly one solution.
Blanks: ask for a number of blank squares, or for as many as possible. When more blanks would allow a second solution, or would take too long to find, you get fewer. An exhaustive option keeps searching for the exact number, which can take a very long time on big puzzles.
Seeds: a seed is a number that picks one particular puzzle. The same seed, size, blanks and options always give the same puzzle, in C# and in JavaScript. Shared test data, made with the C# library, checks this in both languages.
Solver: it solves any puzzle of these sizes that has exactly one solution, and stops with an error when a puzzle is invalid, breaks the rules, or has no solution or more than one.
Conflict checks: find out which row, column or box already holds a number, on the board or before you place it. A number that breaks no rule can still be wrong, so compare it with the solution, which every puzzle carries.
Shuffle: turn a puzzle into an equivalent one, with the same size, difficulty and number of blanks but a different look.
Puzzle codes: write any grid as one line of text and read it back. Each square is one character: 0 for a blank, 1 to 9 as digits, and letters from A for 10 and up, with a dot between rows.

SudokuGen for C#

The C# library NMX.SudokuGen.Library is on NuGet, the package registry for .NET. It targets .NET Standard 2.1 and has no other dependencies, and we use it in Unity for Shaolin Sudoku. Its classes live in the NMX.SudokuGen.Library.Core namespace.

Install: run dotnet add package NMX.SudokuGen.Library in your project folder.
Create: Sudoku.Create(3, 40, 777) makes a 9×9 puzzle with up to 40 blanks from the seed 777. Leave out the seed for a random puzzle.
Solve: Sudoku.Solve(puzzle) solves a puzzle, or throws an exception when it does not have exactly one solution.
Check and shuffle: FindConflicts tells you which row, column or box already holds a number, and Shuffle gives you an equivalent puzzle.
Puzzle codes: Utility.GetPuzzleCode(puzzle) turns a grid into a puzzle code, and Utility.GetPuzzleArr(code) reads one back.

The library keeps no shared state, so it is safe to create, solve and shuffle puzzles on several threads at once.

SudokuGen CLI

SudokuGen CLI is a command-line app built on the C# library. It is on NuGet as the .NET tool NMX.SudokuGen.Cli, and it also comes as standalone binaries.

Install: with the .NET 10 SDK, run dotnet tool install -g NMX.SudokuGen.Cli and then type sudokugen to run it.
Run it once: put dnx NMX.SudokuGen.Cli in place of sudokugen to run it without installing the tool.
Standalone: download a binary for Windows, Linux or macOS from GitHub Releases (opens in a new tab). It needs nothing else installed.

Its commands are create, solve and shuffle. For example, sudokugen create -r 3 -b 40 -s 777 prints the same puzzle as the C# example above. Flags set the rank, the blanks, a seed and how many puzzles to make. It can read puzzle codes from a text file and write to one, draw the result as a board, and spread a big batch across your CPU cores. It exits with code 1 when an argument or a puzzle fails, so it fits in scripts: argument errors go to stderr, and a puzzle that fails gets an Error line in the output.

SudokuGen for JavaScript

The JavaScript library nmx.sudokugen.library is on npm, the package registry for JavaScript. It is written in TypeScript and ships as plain ES modules with type declarations and no dependencies, so it runs in browsers, Node.js, Deno and Bun. It needs an ES2022 runtime: any current browser, or Node.js 20 or later.

Install: run npm install nmx.sudokugen.library in your project. In a browser without a bundler, you can import it from the jsDelivr CDN instead.
Create: Sudoku.create(3, 40, { seed: 777 }) makes the very same puzzle as the C# example.
Solve and more: Sudoku.solve, findConflicts, shuffle, getPuzzleCode and getPuzzleArr work just like their C# twins.

Every call is synchronous. On a desktop, a 9×9 puzzle takes about a millisecond to create, a 16×16 with as many blanks as possible about a tenth of a second, and a 25×25 with as many blanks as possible a few seconds. In a browser, run the big ones in a Web Worker to keep the page responsive, as our web app does.

Used in Shaolin Sudoku

Our game Shaolin Sudoku creates its puzzles with the C# library. Each new game gets a fresh 9×9 puzzle, with 30 blanks for Easy, 45 for Medium, and as many as a single solution allows, up to 60, for Hard. The game also uses the library to check the puzzles you type in yourself in its custom difficulty mode, to check your notes against the numbers on the board, and to write the puzzle codes it shares. Those codes work in the web app too: paste one into Import.

Open source

SudokuGen is free and open source under the MIT License (opens in a new tab). You can use it in free and commercial projects; just keep the copyright and license notice with it.

All of it lives in one repository, on GitHub (opens in a new tab) and GitLab (opens in a new tab): the C# library and CLI, the JavaScript library, tests for both libraries, and the shared test data that keeps every language making the same puzzles. Versions in more languages are planned. Version numbers line up across languages: the same major and minor version means the same features, and the same puzzle for the same seed, in every language.

Made something with SudokuGen, or found a bug? Tell us