Install¶
The wheel ships the bonsai Python package and its compiled extension, nothing else: the bonsai command-line binary is a source-build artifact (Building from source).
The one command¶
pip install bonsai-gbt
That is the whole install story: CPU and CUDA, Linux (x86_64 with GPU support, aarch64) and macOS (arm64), CPython 3.9 through 3.13, from PyPI. The package installs as bonsai-gbt and imports as bonsai. GPU training needs nothing extra beyond an NVIDIA driver; there is no separate GPU package, no CUDA toolkit install, and no 300MB download (the whole wheel is ~2.3MB).
To pin a specific release instead of the index's latest, pip install bonsai-gbt==1.5.0, or point pip straight at a release's attached assets: pip install bonsai-gbt --find-links https://github.com/daniel-m-campos/bonsai/releases/expanded_assets/v1.5.0 (the releases page lists every tag; wheels attach there too).
What ships¶
| platform | architecture | GPU training | wheel |
|---|---|---|---|
| Linux | x86_64 | yes, out of the box | manylinux_2_34, ~2.3MB |
| Linux | aarch64 | no (CPU) | manylinux_2_34 |
| macOS | arm64 | no (CPU) | macosx_14_0 |
Every platform covers CPython 3.9 through 3.13. The Linux tags mean Ubuntu 22.04+/Debian 12+ era glibc; libc++ and the OpenMP runtime are vendored into the wheel, so nothing needs installing beside numpy (which pip pulls automatically).
GPU support in the linux x86_64 wheel¶
The x86_64 wheel carries the CUDA backend whole (decision 70): native code for every real NVIDIA architecture from sm_70 (Volta) through sm_120 (Blackwell consumer), plus a compute_90 PTX floor that forward-JITs on anything newer. The CUDA runtime is statically linked, so you need no CUDA toolkit, only an NVIDIA driver at R525 or newer. On a machine without a GPU the same wheel behaves exactly like a CPU wheel: it imports, trains on CPU, and bonsai.cuda_available() reports False.
Every release's CUDA wheel is validated on rented GPU hardware before it attaches to the release; the claim "pip install, then GPU training works" is tested, not hoped.
Check it works¶
import bonsai
import numpy as np
rng = np.random.default_rng(0)
X_train = rng.random((500, 8), dtype=np.float32)
y_train = (X_train[:, 0] * 2 + rng.normal(0, 0.1, 500)).astype(np.float32)
model = bonsai.BonsaiRegressor(n_iters=20).fit(X_train, y_train)
print("r2:", round(model.score(X_train, y_train), 3))
print("GPU available:", bonsai.cuda_available())
If cuda_available() is True, pass device="cuda" (the XGBoost spelling) or pick a CUDA grower directly with grower="cuda_depthwise" / "cuda_oblivious"; the API tour covers the rest.
The bench extra¶
pip install "bonsai-gbt[bench]"
The extra pulls XGBoost, LightGBM, CatBoost, scikit-learn, pandas, and openml: everything bonsai.bench needs to reproduce the published benchmark tables. python -m bonsai.bench.grinsztajn out.jsonl runs the external standings suite under the benchmark protocol, and --report renders the standings from the finished jsonl; Running the benchmarks walks every suite.
Docker¶
A runtime image with the CUDA wheel preinstalled ships alongside each release:
docker run --gpus all ghcr.io/daniel-m-campos/bonsai:cuda python3 -c "import bonsai; print(bonsai.cuda_available())"
bonsai:cuda tracks the latest release; versioned tags (bonsai:v1.4.0-cuda) pin one. The image carries an sshd entrypoint keyed by a PUBLIC_KEY environment variable, so it boots directly as a RunPod (or similar) GPU pod. The release gate validates this exact image on real hardware before promoting it.
Picking a wheel by hand¶
For locked-down environments or requirements files, install a release asset by direct URL:
pip install https://github.com/daniel-m-campos/bonsai/releases/download/v1.4.0/bonsai_gbt-1.4.0-cp312-cp312-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl
Filename anatomy: cp312 is the CPython version (pick yours, 39 through 313), the platform tag is manylinux_*_x86_64 / manylinux_*_aarch64 / macosx_14_0_arm64, and there is one file per combination on the release page.
No wheel for your platform?¶
The sdist (bonsai_gbt-<version>.tar.gz) is on the release page and pip install will compile it, but that is a full source build: it needs the LLVM/libc++ toolchain described in Building from source, which is also where development setups, the CLI binary, and CUDA source builds live.