First run
Install cuda-doctor and check your machine
The quickstart is intentionally small: diagnose, repair, validate, and then build with the right architecture and toolchain settings.
Quickstart flow
After installation, the first session should answer whether the machine is truly usable.
cuda-doctor doctor
cuda-doctor doctor auto
cuda-doctor validate
cuda-doctor buildOne command at a time
Each command narrows uncertainty. Diagnose first, repair second, validate third, and build only after the stack has passed a real workload.
What to expect from the first diagnosis
- GPU model, compute capability, VRAM, and architecture family.
- Installed driver version and driver health.
- CUDA toolkit version, `nvcc` availability, and local architecture support.
- PyTorch compatibility and whether the local wheel can actually target the GPU.
- Validation risk level when the machine looks healthy on paper but likely fails on execution.
Repair, then prove
`cuda-doctor doctor auto` should behave like a compatibility-aware repair engine, not a blind upgrader. It should preserve the user's existing environment constraints where possible and only move further when the current stack cannot support the detected GPU or workload.
Validation is the final gate. If the smoke test cannot allocate memory, transfer data, launch a kernel, and produce sane output, the install is not healthy.
Related docs
Diagnose
doctor
Run a full environment diagnosis for the GPU, driver, toolkit, runtime, build chain, and validation risk.
Repair
doctor auto
Apply compatible repairs to a broken or misleading CUDA environment and refuse success until validation passes.
Execution
validate
Prove that device selection, memory transfer, kernel launch, and runtime behavior work on the local GPU.