rigsolve¶

Offline-first compatibility resolution for PyTorch, CUDA, and native GPU extensions.

rigsolve detects a machine without importing torch, evaluates driver, CUDA, GPU, Python, PyTorch, and native-extension constraints together, and produces a sourced installation or repair plan.

Install rigsolve

Run the first solve

See what it returns¶

Give rigsolve a package and a target machine. It prints a reviewable plan and keeps evidence limits in the output; it does not install anything unless you explicitly pass --execute.

$ rigsolve solve \
    --want 'flash-attn==2.8.3' \
    --target 'RTX 4090,driver=580.65,python=3.12,linux'
# Generated by rigsolve; review before running.
# Matrix 2026.08.15 (1e066bd53f01); evidence: metadata-backed.
# WARNING: flash-attn's wheel filename does not establish GPU kernel coverage for sm_89
python -m pip install --index-url https://download.pytorch.org/whl/cu126 torch==2.9.0
python -m pip install 'https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3%2Bcu12torch2.9cxx11abiTRUE-cp312-cp312-linux_x86_64.whl#sha256=4e2f9e39313266b1544b68138b15b91ee6221eccf14f7902b7c6620351340810'

What rigsolve provides¶

Joint compatibility checks

Resolve driver, CUDA, GPU architecture, Python, torch, extension, and ABI constraints as one system.

Reviewable plans

Render pip, uv, TOML, Docker, JSON, or Colab output without installing anything by default.

Sourced evidence

Trace matrix facts to their source, date, and evidence level. Unknown combinations remain unknown.

Local verification

Run crash-isolated imports and available GPU probes after installation.

Quick start¶

$ python -m pip install rigsolve
$ rigsolve detect
$ rigsolve solve \
    --want 'flash-attn==2.8.3' \
    --target 'RTX 4090,driver=580.65,python=3.12,linux'

Detection does not import torch. Solving prints a plan for review and does not install packages unless --execute is supplied.

Important

rigsolve reports what its evidence supports. An unrecorded combination remains unknown. A successful solve is not a guarantee that every workload will run.

Choose the right section¶

If you want to	Start here
Install the CLI	Installation
Resolve your first GPU stack	Quickstart
Describe another machine	Target profiles
Diagnose an installed environment	Diagnosis guide
Review output formats	Plans and lockfiles
Understand evidence and limits	Trust and verification model
Use the Python package	Python API
Diagnose unexpected behavior	Troubleshooting

Scope¶

rigsolve focuses on Linux x86_64 systems with NVIDIA CUDA GPUs. It resolves and explains compatibility using recorded evidence. It does not replace package installers, benchmark workloads, guarantee unrecorded combinations, or install a plan without explicit execution.

Documentation map¶

User guide

Reference

Project