---

name: installation-diagnostics description: "Diagnose and fix bitsandbytes installation, import, backend compatibility, native-library loading, and source-build issues." disable-model-invocation: true metadata: disco-role: operating license: MIT

Installation Diagnostics

Use this sub-skill when a task involves installing bitsandbytes, debugging import bitsandbytes, checking CPU/CUDA/ROCm/XPU/HPU/MPS support, interpreting python -m bitsandbytes, choosing a source build, resolving native library load failures, or preparing sanitized environment details for an issue.

Route Here When

• Installation or import fails, or native methods fail after import.
• A user asks whether their Python, PyTorch, CUDA, ROCm, XPU, Gaudi, MPS, CPU, OS, or wheel combination is supported.
• Errors mention libbitsandbytes_cpu, libbitsandbytes_cuda*, libbitsandbytes_rocm*, libcudart, amdhip64, fatbinwrap, no kernel image, Configured CUDA binary not found, or CPU-only native methods.
• The environment uses BNB_CUDA_VERSION or BNB_ROCM_VERSION, or the selected binary does not match PyTorch's reported accelerator runtime.
• The user is in CPU-only CI and needs import/signature/package inspection without GPU kernels.
• The user needs source-build decisions for CUDA, ROCm, CPU, XPU, MPS, Jetson/aarch64, Windows, or macOS.

Do Not Handle Here

• Hugging Face BitsAndBytesConfig, QLoRA, PEFT, Accelerate, Diffusers, or model-loading choices: route to ../transformers-integrations/SKILL.md.
• Direct bitsandbytes.nn, bitsandbytes.functional, quantized layer, state dict, or primitive API usage: route to ../quantized-modules-functions/SKILL.md.
• Optimizer selection, GlobalOptimManager, training-loop integration, or paged optimizer usage: route to ../optimizers-training/SKILL.md.

First Response Workflow

1. Ask for the exact command, traceback, OS/architecture, Python version, PyTorch version, and whether the user expects CPU, CUDA, ROCm, XPU, HPU, or MPS.
2. Prefer read-only checks first: python -m bitsandbytes, python -c "import torch; print(torch.__version__, torch.version.cuda, torch.version.hip, torch.cuda.is_available())", and python scripts/backend-report.py --json from this sub-skill when available.
3. Compare PyTorch's reported runtime (torch.version.cuda or torch.version.hip) plus any BNB_*_VERSION override against the bundled libbitsandbytes_* filenames.
4. Separate import/package inspection from accelerator execution: CPU-only environments can validate imports and signatures but cannot prove CUDA/ROCm/XPU kernels work.
5. Use references/backend-compatibility.md for support matrices and expected binaries, references/source-builds.md for safe build choices, and references/troubleshooting.md for symptom-to-fix guidance.

Safe Commands

python -m bitsandbytes
python sub-skills/installation-diagnostics/scripts/backend-report.py --help
python sub-skills/installation-diagnostics/scripts/backend-report.py --json
python -c "import bitsandbytes, torch; print(bitsandbytes.__version__, torch.__version__)"

Avoid running GPU optimizer or quantized model smoke tests unless the user confirms accelerator hardware is available and they want kernel execution. Avoid installer scripts that download or mutate CUDA/ROCm; distill their intent into source-build guidance instead.

Issue Info Checklist

Collect only sanitized details: OS and architecture, Python/PyTorch/bitsandbytes versions, torch.version.cuda or torch.version.hip, torch.cuda.is_available(), visible device names if the user agrees, BNB_CUDA_VERSION/BNB_ROCM_VERSION values, expected/bundled native library names, the minimal traceback, and whether the install came from a wheel or source build. Do not include access tokens, usernames, full home paths, private project paths, or complete environment dumps.