pencil-puzzles

pencil-puzzles generates, solves and rates pencil puzzles such as sudoku, nurikabe and kakuro. It is a Python package with a Rust engine, a command-line tool and a web app for playing in the browser.

Every generated puzzle has exactly one solution, and a brute-force solver proves it. A puzzle’s difficulty is the level of the hardest technique a person needs to solve it. An expert sudoku needs a technique such as an X-wing.

pip install pencil-puzzles

import pencil_puzzles as pp

game = pp.generate("sudoku", difficulty="hard")
print(game.puzzle)

Start with the quickstart. The user guide covers each part of the package, and the API reference lists every name.

Genres

Genre	Goal	Standard size	Largest
Fillomino	Divide the grid into regions whose cells hold the region’s size; same-size regions never share a side.	10×10	10×10
Hashi	Connect all islands with straight bridges that never cross, giving each island as many bridges as its number.	10×10	15×15
Hitori	Shade cells so no unshaded number repeats in a row or column; shaded cells never share a side and unshaded cells stay connected.	8×8	12×12
Kakurasu	Shade cells so each row and column clue is the sum of its shaded cells’ positions.	7×7	32×32
Kakuro	Fill the white cells with digits 1–9 so each run adds up to its clue without repeating a digit.	10×10	16×16
Nurikabe	Shade a connected sea, leaving islands the size of their numbers and no shaded 2×2 block.	10×10	10×10
Sudoku	Fill rows, columns and boxes with each digit exactly once.	9×9	9×9 (also 4×4)

Each genre’s page has its rules, techniques, parameters and formats.