Implementation:Bitsandbytes foundation Bitsandbytes Diagnostics CLI
| Knowledge Sources | |
|---|---|
| Domains | Diagnostics, CLI, Installation |
| Last Updated | 2026-02-07 13:31 GMT |
Overview
User-facing CLI diagnostics tool that prints environment information, verifies GPU availability, and performs a sanity check to validate the bitsandbytes installation.
Description
The diagnostics CLI is the primary tool for users to verify their bitsandbytes installation. Invoked via python -m bitsandbytes, it prints: (1) bitsandbytes version, (2) platform and OS details, (3) Python version, (4) PyTorch version with CUDA/HIP/XPU status, (5) related package versions (accelerate, transformers, peft, triton, etc.), (6) CUDA diagnostics if a GPU is detected, and (7) a sanity check that runs a full forward-backward-step cycle using an 8-bit Adam optimizer on CUDA. If any step fails, it provides debugging guidance.
Usage
Run when troubleshooting bitsandbytes installation issues or verifying that GPU quantization is working correctly. The output is designed to be included in bug reports.
Code Reference
Source Location
- Repository: bitsandbytes
- File: bitsandbytes/diagnostics/main.py
- Lines: 1-118
Signature
def main() -> None:
"""Main diagnostics entry point."""
def sanity_check() -> None:
"""Run forward-backward-step with Adam8bit on CUDA."""
def show_environment() -> None:
"""Print platform, Python, PyTorch, and related package versions."""
def get_package_version(name: str) -> str:
"""Return installed version of named package or 'not found'."""
Import
# Via command line:
# python -m bitsandbytes
# Or programmatically:
from bitsandbytes.diagnostics.main import main
main()
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | No inputs; reads system state directly |
Outputs
| Name | Type | Description |
|---|---|---|
| stdout | Text | Formatted environment info, diagnostics, and sanity check result |
| exit code | int | 0 on success, 1 on failure |
Usage Examples
Running Diagnostics
# Run from command line
python -m bitsandbytes
# Example output:
# ===================================
# bitsandbytes v0.43.0
# ===================================
# Platform: Linux-6.2.0-x86_64
# Python: 3.10.12
# PyTorch: 2.1.0
# CUDA: 12.1
# Related packages:
# accelerate: 0.24.1
# transformers: 4.35.0
# ...
# SUCCESS!