♞ ChessMG

Blazing-fast chess move generation for Python, powered by a C++20 bitboard engine.

One pip install. 200 million moves per second. A Python API that stays out of your way.

Why ChessMG?


Fast	Magic bitboards + zero-copy Cython bindings — roughly 50× faster than pure-Python move generators
Pythonic	A clean `ChessPosition` / `Move` API with type annotations, UCI notation and rich move metadata
Complete	Castling, en passant, promotions, check / checkmate / stalemate detection, legality checks
Verified	Move generation validated against the standard perft reference values up to depth 8
Lean	No runtime dependencies beyond NumPy — and less than 1 MB per position

Typical uses: engine prototyping, puzzle solvers, dataset generation for ML, move validation backends, perft research — anywhere Python convenience meets the need for raw speed.

🚀 Quick Start

Install

pip install chessmg

Prebuilt wheels cover Linux (x86_64, aarch64) and macOS (Intel, Apple Silicon) for Python 3.9–3.13. On other platforms pip falls back to building from source.

Or install the latest development version from source:

git clone https://github.com/osick/ChessMG.git
cd ChessMG
pip install .

Building from source requires a C++20 compiler (g++/clang), Cython and numpy.

Play

from chessmg import ChessPosition

pos = ChessPosition()                # standard starting position (or pass any FEN)

for move in pos.legal_moves():       # 20 legal moves, as rich Move objects
    print(move.uci)                  # "e2e4", "g1f3", ...

pos.make_move("e2e4")                # UCI strings or Move objects
pos.make_move("e7e5")
print(pos.fen)                       # rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6 0 2

pos.undo_move()                      # take it back

print(pos.turn)                      # Color.BLACK
print(pos.is_checkmate)              # False

print(ChessPosition().perft(6))      # 119060324 — in about half a second

Promotions, castling and en passant just work:

pos = ChessPosition("8/4P1k1/8/8/8/8/8/4K3 w - - 0 1")
pos.make_move("e7e8q")               # promote to queen
print(pos.fen)                       # 4Q3/6k1/8/8/8/8/8/4K3 b - - 0 1

📖 API at a Glance

`ChessPosition`

Member	Description
`ChessPosition(fen)`	Create position from FEN — raises `ValueError` on invalid or illegal input
`legal_moves()`	List of legal `Move` objects
`make_move(move)`	Play a move (UCI string or `Move`); full move semantics
`undo_move()`	Undo the last move
`fen`	Current position as a complete 6-field FEN string
`turn`	Side to move (`Color.WHITE` / `Color.BLACK`)
`is_check` / `is_checkmate` / `is_stalemate` / `is_game_over`	Game state
`perft(depth)`	Count leaf nodes at the given depth
`copy()`	Independent copy of the position

`Move`

Property	Description
`from_square` / `to_square`	Square indices (0–63)
`from_square_name` / `to_square_name`	Algebraic notation (`"e2"`)
`uci`	UCI notation (`"e2e4"`, `"e7e8q"`)
`promotion`	`PieceType` for promotions, else `None`
`Move.from_uci("e2e4")`	Construct from a UCI string

Legacy low-level API (click to expand)

For backward compatibility, the lower-level API remains available:

from chessmg import ChessMoveGenerator, perft, moves

gen = ChessMoveGenerator("r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1")
arr = gen.moves()          # numpy array of shape (n_moves, 3): [from, to, flags]
n   = perft(fen, depth)    # one-shot perft; returns 0 for illegal positions

See chessmg/README.md for details.

🏁 Performance

Perft from the starting position, single-threaded (AMD Ryzen, g++ -O2):

Depth	Nodes	Time	Speed
5	4,865,609	< 0.1 s	~166M NPS
6	119,060,324	0.5 s	~218M NPS
7	3,195,901,860	12.9 s	~247M NPS
8	84,998,978,956	6.7 min	~213M NPS

All results match the published perft reference values exactly.

How it's fast: magic bitboards for sliding pieces, pre-computed attack tables, perfect-hash lookups, cache-friendly data layout in the C++20 core — and Cython bindings that avoid copying on the way into Python.

Reproduce it yourself:

python tests/benchmark_perft.py
python tests/test_perft_start_fen.py 7 verbose

🗂️ Project Structure

ChessMG/
├── chessmg/              # Python package
│   ├── position.py       #   High-level API (ChessPosition, Move)
│   ├── libchessmg.pyx    #   Cython bindings
│   └── libcmg/           #   C++20 engine
│       ├── libcmg.*      #     Position wrapper, game states, perft
│       ├── libsurge.*    #     Bitboard core (based on surge)
│       └── tests/        #     C++ unit tests
├── tests/                # Python test suite + benchmarks
├── examples/             # Example scripts
└── docs/                 # Technical documentation

🛠️ Development

# Editable install with dev tools (pytest, black, mypy, pytest-cov)
pip install -e ".[dev]"

# Rebuild the extension in place after C++/Cython changes
python setup.py build_ext --inplace

# Run the test suite
pytest tests/

# Script-style correctness / perft tests (also run by `make test`)
python tests/test_correctness.py verbose
python tests/test_perft_start_fen.py 6 verbose
python tests/test_set_position.py verbose

📄 License

MIT License — see LICENSE. Third-party attribution is in NOTICE; it is kept out of LICENSE so the file stays byte-identical to the canonical MIT text and licence scanners classify it correctly.

Acknowledgments

surge — the C++ bitboard engine ChessMG's core is based on

ChessMG — chess move generation at engine speed, with Python comfort.

Report an issue · Documentation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chessmg-0.6.0.tar.gz (185.6 kB view details)

Uploaded Aug 20, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

chessmg-0.6.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (711.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chessmg-0.6.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (697.6 kB view details)

Uploaded Aug 20, 2026 CPython 3.13manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

chessmg-0.6.0-cp313-cp313-macosx_11_0_x86_64.whl (280.6 kB view details)

Uploaded Aug 20, 2026 CPython 3.13macOS 11.0+ x86-64

chessmg-0.6.0-cp313-cp313-macosx_11_0_arm64.whl (277.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.13macOS 11.0+ ARM64

chessmg-0.6.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (713.4 kB view details)

Uploaded Aug 20, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chessmg-0.6.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (699.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.12manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

chessmg-0.6.0-cp312-cp312-macosx_11_0_x86_64.whl (281.0 kB view details)

Uploaded Aug 20, 2026 CPython 3.12macOS 11.0+ x86-64

chessmg-0.6.0-cp312-cp312-macosx_11_0_arm64.whl (278.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.12macOS 11.0+ ARM64

chessmg-0.6.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (723.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chessmg-0.6.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (712.9 kB view details)

Uploaded Aug 20, 2026 CPython 3.11manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

chessmg-0.6.0-cp311-cp311-macosx_11_0_x86_64.whl (283.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.11macOS 11.0+ x86-64

chessmg-0.6.0-cp311-cp311-macosx_11_0_arm64.whl (278.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.11macOS 11.0+ ARM64

chessmg-0.6.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (697.3 kB view details)

Uploaded Aug 20, 2026 CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chessmg-0.6.0-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (688.1 kB view details)

Uploaded Aug 20, 2026 CPython 3.10manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

chessmg-0.6.0-cp310-cp310-macosx_11_0_x86_64.whl (284.1 kB view details)

Uploaded Aug 20, 2026 CPython 3.10macOS 11.0+ x86-64

chessmg-0.6.0-cp310-cp310-macosx_11_0_arm64.whl (278.4 kB view details)

Uploaded Aug 20, 2026 CPython 3.10macOS 11.0+ ARM64

chessmg-0.6.0-cp39-cp39-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (695.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.9manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chessmg-0.6.0-cp39-cp39-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (685.3 kB view details)

Uploaded Aug 20, 2026 CPython 3.9manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

chessmg-0.6.0-cp39-cp39-macosx_11_0_x86_64.whl (284.5 kB view details)

Uploaded Aug 20, 2026 CPython 3.9macOS 11.0+ x86-64

chessmg-0.6.0-cp39-cp39-macosx_11_0_arm64.whl (278.9 kB view details)

Uploaded Aug 20, 2026 CPython 3.9macOS 11.0+ ARM64

File details

Details for the file chessmg-0.6.0.tar.gz.

File metadata

Download URL: chessmg-0.6.0.tar.gz
Upload date: Aug 20, 2026
Size: 185.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chessmg-0.6.0.tar.gz
Algorithm	Hash digest
SHA256	`132a7b7fc7cea5c489f1e3138aacd9bcba2c500d387bd56a59c5b10c437286f6`
MD5	`c26205aaa57f6b43d1712534e738cdcf`
BLAKE2b-256	`543a22c7947c5dfce33afd36655552e94124d49b61583c99e24739ceec4f60e8`

Algorithm	Hash digest
SHA256	`3aeb9574ef69fa7c3cb88075522411a2a9a8101a2943e6d778fc942a6c23613f`
MD5	`7423c05a054067de330d9e6d4ffc0e08`
BLAKE2b-256	`588dd092ff33c5a409f60651c37c56a1483b6f23ad361fd4814ed9b22e53e275`

Algorithm	Hash digest
SHA256	`21af7670c2af4babe0f9bf1c87efb48c067ab7e6b0aa7db94803d0a85eb943ef`
MD5	`2021e22f112da909248ed84bba10b06c`
BLAKE2b-256	`f27748e43c0c4031357b6371ecbd7563d80bfcf9b1def230d9f701cc44147770`

Algorithm	Hash digest
SHA256	`2c3958225cc829042c467125e7ebd15659cf9df10c454a41fc0961d402388bef`
MD5	`5eb777448c71997e39b7c7f5ff0b6b4e`
BLAKE2b-256	`f0b39efc420d7365d6e968b5e01e1e3cf04fb07ba3f3669c82407c628b2bc84a`

Algorithm	Hash digest
SHA256	`e56609d06b86e3d732adff89b1e696fc1f4aa1ca2b7714fc0efdcf29169f3b40`
MD5	`7e05860ca335787dc270a6dc1835d55e`
BLAKE2b-256	`85178f1db769d82bd3763ead853de96032684b155a6ffcd5a72b9a7c4ede225e`

Algorithm	Hash digest
SHA256	`efec9174854b873e4fe6009c6165e9bb9c5e5586810699bcf03abce0a3ec6d10`
MD5	`71a04474fc2ba52c95b600c71c28b4a2`
BLAKE2b-256	`a7353d760869b749d5b66ea8d4095686b14b3ea69ada54f73d2be9610ae71ea4`

Algorithm	Hash digest
SHA256	`3c3f230fae38b443cc8cf13d86e30414a9b1451f62217f4e7ecf4f347262c36e`
MD5	`518cfdaf902f70a3556243e9266f48f9`
BLAKE2b-256	`ec1cba1d4aa815fcdbc5cfd2469cb4a8df7e95a4a2e407a11256db5117e65409`

Algorithm	Hash digest
SHA256	`6068556f3617a1609bf69c53ef8e28a6d4cac64e1eb09b20b8ced6bbaa3fd5b9`
MD5	`41643270e867d3372df79bcab1cfc073`
BLAKE2b-256	`848686b3aa3bf29dd75881f280033796079e3618b819174b7e4ee74f3fed407d`

Algorithm	Hash digest
SHA256	`ecfae4baaba8ed68fcb2985b0b3ef4f13726a7b130e1fdb2ddc3a6a4629e7c1d`
MD5	`89df314d868474bd13fa4343a94e2d69`
BLAKE2b-256	`cf0e05d9d3d481e1b2f9b11c38df25214316874ec24f00c77250d5ca048e0f3b`

Algorithm	Hash digest
SHA256	`59325f401390cacfe48d70a29aa42a0ebdde3adeb93e04e2158ce9e3dec093fc`
MD5	`47d039c0fc034b8d736d37d93f0a3ef6`
BLAKE2b-256	`c7ecf1ffcc76bc16f97c77da8acfe8beec428ce0bf448d79f3caed9e7fc4b10f`

Algorithm	Hash digest
SHA256	`2ea40601d2446ee9f58b2694ebb5bbe6e03db566f07fd019f257eb9733a39338`
MD5	`0af4eb7e8f6eec0d44110b43cc5fd3a9`
BLAKE2b-256	`afe60e3a74ba48c237a2ed1b3a96bf837412965dff4ae1055ae3b1907e255eff`

Algorithm	Hash digest
SHA256	`647f6faa447278c2e3fd7023b36318b5cfc0415e17b8cf5646d34760d9b29285`
MD5	`a601a3bae195c62d3ec68026d81531c1`
BLAKE2b-256	`4f79add90521d87941c49c45e759171a2bbaabe441300e59a2a4e8a8644dd84e`

Algorithm	Hash digest
SHA256	`7d11dd66b016c223b9cf75138162c54fe8cb07712fc98e0babfb65a70938784d`
MD5	`65df5b6e2879ffd577cf74cbdeca2dcf`
BLAKE2b-256	`fc436413fd46f8572d5946eb6dbe585635035cf700b2d60b7550feccdf3eb851`

Algorithm	Hash digest
SHA256	`a2c686af3ca620446a51dd96fb699a9a3439cf72a1ee8cb6b3595dfae411d598`
MD5	`6b418d24c6b31ac1a501c2316409eb17`
BLAKE2b-256	`e0ba7706879695f6025613cc9d0f7e4984ce1f0ff865eeebc01e24172620188a`

Algorithm	Hash digest
SHA256	`0be8ed4e2261698dcf5d943bbd6ca30ea1aa2dec6414d1d8a7904a8316e41748`
MD5	`b227cef87b373d824949ac5ba16b866a`
BLAKE2b-256	`c95f689b5f216552fb4fa5b8e2ef2d300b45fe61b5fc35f08947431647b07a51`

Algorithm	Hash digest
SHA256	`15d32ea841d240d0768aab973b37030c1f4a827a9a9c4c2d5559ada74eb9804c`
MD5	`64b49d02751242da17497892cbc85116`
BLAKE2b-256	`0ee5900450ee39293a43f80896636e7f3d4784350ce6a84d960d2d5cb92dde75`

Algorithm	Hash digest
SHA256	`25be4d856f4ad6292a6d5211cbd3ee853ed6435f339e7b46d8b0fb8a72f45890`
MD5	`d4e491356974b18d9038c80b0a9fcb96`
BLAKE2b-256	`122a502d1fa2f5c316df72018e51fdd0127c6816fed3d068f89ab024be62a4e3`

Algorithm	Hash digest
SHA256	`c5a762ee6de880e7eb8067c9732f6b7ff62c0aca83cb891fb8c9a99180138e1c`
MD5	`ea41744cf5c908ed75a75d412bbfb1eb`
BLAKE2b-256	`a791e1d8ba43db52eda174eb410c55aa72e0a47c372764e6dacf6f458e206eb4`

Algorithm	Hash digest
SHA256	`15d8c1370b8549d46358534b6a0aa0a4a1767db6320673a4ccf0ecc62935544b`
MD5	`196bc50048d7dbe5fa66284eeb956125`
BLAKE2b-256	`7c6f42a8748e95d73a63f63d445d2656d67b09b3c48da83750546c0e0e0caffe`

Algorithm	Hash digest
SHA256	`5e9345f3b54a5f253e3e72d1d4efe97afa5bbe947a00963f0f02689b759e5ff9`
MD5	`9167f904875e36fc209a1d47df606dbb`
BLAKE2b-256	`4d399679ba81455eb2490de1d8aaac6003d6b45ceb5b7070dbcf6e0673d44bd2`

Algorithm	Hash digest
SHA256	`c16cf14552a50968f87639b703e7e5f1ae636839097e4b761703aa890860c44f`
MD5	`d25478d8ccd7dd0604a38ffb394d9b66`
BLAKE2b-256	`2ede7090b4a3967743e2bb68bc8b137ece97ec95de8222e7e2d13853250b0b44`

chessmg 0.6.0

♞ ChessMG

Why ChessMG?

🚀 Quick Start

Install

Play

📖 API at a Glance

ChessPosition

Move

🏁 Performance

🗂️ Project Structure

🛠️ Development

📄 License

Acknowledgments

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

`ChessPosition`

`Move`