GNU Backgammon (GNUBG)

GNU Backgammon Python bindings bring the powerful GNUBG engine to Python 3.

Quick Start

gnubg is a native Python extension module that wraps the GNU Backgammon engine, so you can call the same position-analysis and cube-decision routines that power the GUI from any Python 3.8–3.13 script or application. It’s ideal for batch processing, data-science workflows, or building custom tools and UIs.

Installation

pip install gnubg

Getting Started

import gnubg

# Load the engine (weights, bear-off tables, etc. are initialized)
gnubg.initnet()

# Convert a position key (20-char A–Z or 14-char Base64) to a board
board = gnubg.boardfromkey("4HPwATDgc/ABMA")

# Evaluate win/gammon/backgammon probabilities and equity at 4 plies
win, gamm, bg, equity = gnubg.probabilities(board, 4)

print(f"Win: {win:.3f}, Gammon: {gamm:.3f}, Backgammon: {bg:.3f}, Equity: {equity:.3f}")

That’s all you need to get up and running! For detailed API docs, advanced build options, and configuration, see the sections below or visit the full documentation on ReadTheDocs.

Data files: Weights, bearoff tables, and match-equity data are included in the package and loaded from the directory next to the compiled extension (gnubg/data). No environment variable is required for normal installs. To override the location (e.g. for a custom build), set GNUBG_DATA_DIR to the directory containing gnubg.weights.

API style: All functions in the C extension are also available in snake_case format (e.g., find_best_move instead of findbestmove, position_from_id instead of positionfromid). The original camelCase names remain available for backward compatibility. The snake_case variants are the recommended idiomatic Python API.

Examples: Example projects (e.g. a REST API for best-move and evaluation) are distributed with the package under gnubg/examples/. After installing, find them with import gnubg, os; print(os.path.join(os.path.dirname(gnubg.__file__), 'examples')). See the README.md in that directory for how to run them.

• ReadTheDocs https://gnubg.readthedocs.io/en/latest/
• Website: https://www.gnu.org/software/gnubg/
• Original Documentation: http://www.gnubg.org/documentation/doku.php?id=gnu_backgammon_faq
• Mailing list: https://lists.gnu.org/mailman/listinfo/gnubg
• Source code: https://github.com/StonesAndDice/gnubg-pypi
• GNUBG Project: https://git.savannah.gnu.org/cgit/gnubg/gnubg-nn.git
• Contributing: https://savannah.gnu.org/people/
• Credits: https://git.savannah.gnu.org/cgit/gnubg.git/tree/credits.sh

It provides:

• Engine initialization & data loading (neural-net weights, opening-book, bear-off tables)
• Position classification (classify) & public-evaluation best move (pub_best_move)
• Board ↔ ID conversions (board_from_position_id, board_from_position_key, key_of_board, position_id)
• Dice utilities (roll) & cube utilities (best_move, pub_eval_score)
• Bear-off tools (bearoff_id_2_pos, bearoff_probabilities)
• Legal-move enumeration (moves) & probabilistic evaluation (probabilities)
• Monte-Carlo rollouts (rollout, cubeful_rollout)
• Equity lookup (equities.value(xAway, oAway))
• Runtime engine tuning via the set submodule

🧪 Platform Compatibility

Python Version	Linux x86_64 (glibc ≥ 2.17)	Linux i686 (glibc ≥ 2.12)	macOS universal2	Windows x86_64
3.14	✅	✅	✅ (macOS ≥ 10.14)	✅
3.13	✅	✅	✅ (macOS ≥ 10.14)	✅
3.12	✅	✅	✅ (macOS ≥ 10.14)	✅
3.11	✅	✅	✅ (macOS ≥ 10.9)	✅
3.10	✅	✅	✅ (macOS ≥ 10.9)	✅

Notes:

• ✅ = Built and available
• ❌ = Not built
• macOS universal2 = Supports both ARM64 and x86-64 architectures

Building on Windows (local)

To reproduce the Windows CI build locally and debug failures:

1. Install MSYS2 (e.g. from msys2.org), then in an MSYS2 UCRT64 shell install dependencies:

   pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-pkg-config \
     mingw-w64-ucrt-x86_64-glib2 mingw-w64-ucrt-x86_64-gmp \
     mingw-w64-ucrt-x86_64-readline mingw-w64-ucrt-x86_64-sqlite3 \
     mingw-w64-ucrt-x86_64-libpng mingw-w64-ucrt-x86_64-gettext

2. In PowerShell (from the repo root), run the build script (same steps as .github/actions/build-wheel on windows-latest):

   .\scripts\build-windows-local.ps1

   This runs meson setup / meson compile only. To also build wheels with cibuildwheel:

   .\scripts\build-windows-local.ps1 -Wheel

   If MSYS2 is not in C:\msys64, set $env:MSYS2_ROOT before running (e.g. $env:MSYS2_ROOT = "D:\msys64").

Testing

The gnubg package has basic unit testing. After installation, run:

python3 -m unittest discover -s gnubg.tests

AI-Assisted Development

Parts of this project were developed with the assistance of generative AI tools.

Specifically, the following models were used:

• GPT-4o (OpenAI ChatGPT)
• o4-mini-high (OpenAI ChatGPT)

These models were used to assist with code generation, documentation drafting, and architectural guidance. All outputs were reviewed and curated by a human before inclusion.

⚠️ Disclaimer:
Although human-reviewed, some AI-generated content may contain mistakes, inaccuracies, or outdated practices. Contributors and users should critically assess all code, comments, and documentation. We welcome corrections and improvements via pull requests or issues.

Code of Conduct

Please read the Code of Conduct to learn how to interact positively.

Contributing

Your expertise and enthusiasm are welcome! You can contribute by:

• Reviewing and testing pull requests
• Reporting and triaging issues
• Improving documentation, tutorials, and examples
• Enhancing engine parameters or submodules
• Maintaining website or branding assets
• Translating materials
• Assisting with outreach and onboarding
• Writing grant proposals or helping with fundraising

For more information, see our Contributing Guide. If you’re unsure where to start, open an issue or join the discussion on our mailing list!

Acknowledgments

This project builds upon the extensive work of the GNU Backgammon (GNUBG) community. Specifically the pygnubg program developed by Joseph Heled.

We express our gratitude to all contributors who have dedicated their time and expertise to the development of GNUBG.

• AUTHORS.md: A list of primary contributors to the gnubg project can be found here.
• GNUBG credits.sh: For a comprehensive list of contributors to the core GNUBG project, please refer to the credits.sh file.

We also thank the broader GNUBG community, including testers, translators, and mailing list participants, for their invaluable support.