Installation

Requirements

• Python ≥ 3.10 (3.10 – 3.14 supported)

• PyTorch ≥ 2.0

---

Quick install (recommended)

Precompiled CPU wheels are published to PyPI for Linux (x86_64, aarch64), macOS (Intel and Apple Silicon), and Windows (x86_64):

pip install pygrog

Verify the installation:

python -c "import pygrog._pygrog_torch as e; assert hasattr(e, 'scatter_add'); import pygrog; print('pygrog', pygrog.__version__, '-- OK')"

---

CUDA wheels

CUDA wheels are not on PyPI (manylinux rules forbid CUDA runtime libraries in standard wheels). They are attached as assets to every GitHub Release.

Use this torch-scatter-style flow (-f is equivalent to --find-links):

# 1) Pick the CUDA label that matches your installed torch wheel
#    Supported values: cu126 | cu128 | cu130
CUDA=cu128

# 2) Pick the pygrog version tag from GitHub Releases
PYGROG_VERSION=1.0.0

# 3) Install from the release asset index
pip install "pygrog==${PYGROG_VERSION}+${CUDA}" \
  -f "https://github.com/FiRMLAB-Pisa/pygrog/releases/expanded_assets/v${PYGROG_VERSION}"

Compatibility map:

CUDA version	Matches PyTorch index	Label
12.6	cu126	+cu126
12.8	cu128	+cu128
13.0	cu130	+cu130

Equivalent explicit form (replace <version> and <cu>):

pip install "pygrog==<version>+<cu>" \
  --find-links https://github.com/FiRMLAB-Pisa/pygrog/releases/expanded_assets/v<version>

Example for CUDA 12.6:

pip install "pygrog==1.0.0+cu126" \
  --find-links https://github.com/FiRMLAB-Pisa/pygrog/releases/expanded_assets/v1.0.0

Tip

Match the CUDA version to the PyTorch wheel you already have installed: python -c "import torch; print(torch.version.cuda)".

---

Build from source

If no precompiled wheel matches your platform (e.g. exotic Linux distro, custom Python build), pip falls back to a source build automatically. A C++17 compiler and CMake are required.

1. Install the C++ toolchain

Linux (requires sudo):

sudo ./scripts/install_build_deps.sh                              # C++ only
sudo ./scripts/install_build_deps.sh --cuda                       # C++ + CUDA 12.6
sudo ./scripts/install_build_deps.sh --cuda --cuda-version=12.8   # CUDA 12.8
sudo ./scripts/install_build_deps.sh --cuda --cuda-version=13.0   # CUDA 13.0

Supported distributions: Ubuntu/Debian, Fedora/RHEL/Rocky, openSUSE/SLES, Arch.

macOS (no sudo):

./scripts/install_build_deps.sh

Requires Homebrew and Xcode Command Line Tools. CUDA is not supported on macOS.

Windows (Administrator PowerShell):

.\scripts\install_build_deps.ps1                          # C++ only
.\scripts\install_build_deps.ps1 -Cuda                    # C++ + CUDA 12.6
.\scripts\install_build_deps.ps1 -Cuda -CudaVersion 12.8  # CUDA 12.8
.\scripts\install_build_deps.ps1 -Cuda -CudaVersion 13.0  # CUDA 13.0

2. Install PyGROG

First install PyTorch and the build tools into the active environment:

pip install torch numpy
# or for a CUDA build:
# pip install torch numpy --index-url https://download.pytorch.org/whl/cu126

# Build tools (required with --no-build-isolation)
pip install scikit-build-core setuptools-scm

Then install PyGROG:

pip install --no-build-isolation pygrog                           # auto-detects CUDA
PYGROG_NO_CUDA=1 pip install --no-build-isolation pygrog          # force CPU-only
PYGROG_FORCE_CUDA=1 pip install --no-build-isolation pygrog       # fail if no CUDA found

Or pass the flag through pip’s CMake interface:

pip install --no-build-isolation pygrog -C cmake.define.PYGROG_NO_CUDA=ON

Note

--no-build-isolation is required whenever torch is installed in a conda or virtualenv environment. With build isolation disabled, pip no longer auto-installs [build-system].requires, so the pip install scikit-build-core ... step above is mandatory.

3. Verify

python scripts/verify_install.py

---

Precompiled wheel matrix

Platform	Architectures	Python	Notes
Linux	x86_64, aarch64	3.10 – 3.14	manylinux2014, PyPI
macOS	x86_64 (Intel), arm64 (Apple Silicon)	3.10 – 3.14	macOS 12+, PyPI
Windows	x86_64	3.10 – 3.14	PyPI
Linux (CUDA 12.6)	x86_64	3.10 – 3.14	GitHub Releases
Linux (CUDA 12.8)	x86_64	3.10 – 3.14	GitHub Releases
Linux (CUDA 13.0)	x86_64	3.10 – 3.14	GitHub Releases

---

Troubleshooting

Build fails — no C++ compiler

error: command 'gcc' failed

Install the C++ toolchain first:

# Linux
sudo ./scripts/install_build_deps.sh

# macOS
./scripts/install_build_deps.sh

# Windows (Admin PowerShell)
.\scripts\install_build_deps.ps1

Build fails — CUDA not found

CMake Error: PYGROG_FORCE_CUDA is set but no CUDA compiler was found.

Either install the CUDA toolkit (--cuda flag above) or build CPU-only:

PYGROG_NO_CUDA=1 pip install pygrog

Wrong CUDA version

Check the CUDA version that matches your installed PyTorch:

python -c "import torch; print(torch.version.cuda)"

Then pick the corresponding CUDA wheel (cu126, cu128, or cu130).

Verify the installation

python scripts/verify_install.py

The script checks the import, the pre-built C++ extension, CUDA availability, and runs a CPU (and optionally CUDA) scatter/gather smoke test. Exit code 0 means everything is working.