{"record":{"id":"8fac3b3431e6d5bf","repo":"Lightning-AI/pytorch-lightning","slug":"str-bitsandbytes-available","errorCode":null,"errorMessage":"str(_BITSANDBYTES_AVAILABLE)","messagePattern":"str\\(_BITSANDBYTES_AVAILABLE\\)","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/plugins/precision/bitsandbytes.py","lineNumber":206,"sourceCode":"                quant_state=quant_state,\n                blocksize=param.blocksize,\n                compress_statistics=param.compress_statistics,\n                quant_type=param.quant_type,\n                quant_storage=param.quant_storage,\n                module=param.module,\n                bnb_quantized=param.bnb_quantized,\n            )\n        return torch.nn.Parameter(data, requires_grad=data.requires_grad)\n    param.data = data\n    if isinstance(param, bnb.nn.Params4bit):\n        param.quant_state = quant_state\n    return cast(torch.nn.Parameter, param)\n\n\n@functools.lru_cache(maxsize=1)\ndef _import_bitsandbytes() -> ModuleType:\n    if not _BITSANDBYTES_AVAILABLE:\n        raise ModuleNotFoundError(str(_BITSANDBYTES_AVAILABLE))\n    # configuration for bitsandbytes before import\n    nowelcome_set = \"BITSANDBYTES_NOWELCOME\" in os.environ\n    if not nowelcome_set:\n        os.environ[\"BITSANDBYTES_NOWELCOME\"] = \"1\"\n    warnings.filterwarnings(\"ignore\", message=r\".*bitsandbytes was compiled without GPU support.*\")\n    warnings.filterwarnings(\n        \"ignore\", message=r\"MatMul8bitLt: inputs will be cast from .* to float16 during quantization\"\n    )\n    import bitsandbytes as bnb\n\n    if not nowelcome_set:\n        del os.environ[\"BITSANDBYTES_NOWELCOME\"]\n\n    class _Linear8bitLt(bnb.nn.Linear8bitLt):\n        \"\"\"Wraps `bnb.nn.Linear8bitLt` and enables instantiation directly on the device and re-quantizaton when loading\n        the state dict.\"\"\"\n\n        def __init__(self, *args: Any, device: Optional[_DEVICE] = None, threshold: float = 6.0, **kwargs: Any) -> None:","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/plugins/precision/bitsandbytes.py#L188-L224","documentation":"_import_bitsandbytes lazily imports the bitsandbytes package; if the import failed at module load time, _BITSANDBYTES_AVAILABLE holds the underlying exception and it is re-raised as ModuleNotFoundError. It is triggered from BitsandbytesPrecision init, convert_module, and _replace_param.","triggerScenarios":"Using BitsandbytesPrecision without bitsandbytes installed, or with a bitsandbytes install that fails to import (broken CUDA libs, wrong wheel for the platform).","commonSituations":"Forgetting `pip install bitsandbytes`, CPU-only environments where bitsandbytes can't load, or CUDA/bitsandbytes version mismatches producing an ImportError at import time.","solutions":["Install bitsandbytes: `pip install bitsandbytes` (or `pip install lightning[bitsandbytes]`)","Verify `python -c \"import bitsandbytes\"` and resolve any underlying ImportError (CUDA toolkit, wheel version)","On unsupported platforms, remove the BitsandbytesPrecision plugin"],"exampleFix":"# before\nfabric = Fabric(plugins=BitsandbytesPrecision(mode=\"nf4\"))  # ModuleNotFoundError\n\n# after\n# pip install bitsandbytes\nfabric = Fabric(plugins=BitsandbytesPrecision(mode=\"nf4\"))","handlingStrategy":"validation","validationCode":"from lightning.fabric.plugins.precision.bitsandbytes import _BITSANDBYTES_AVAILABLE\nif not _BITSANDBYTES_AVAILABLE:\n    raise SystemExit(\"bitsandbytes missing: pip install bitsandbytes\")","typeGuard":"def bitsandbytes_ready() -> bool:\n    from lightning.fabric.plugins.precision.bitsandbytes import _BITSANDBYTES_AVAILABLE\n    return bool(_BITSANDBYTES_AVAILABLE)","tryCatchPattern":"try:\n    import bitsandbytes  # noqa\n    HAS_BNB = True\nexcept ImportError:\n    HAS_BNB = False\nplugins = [BitsandbytesPrecision(mode=\"nf4\")] if HAS_BNB else []","preventionTips":["Install lightning[bitsandbytes] when using the plugin","Smoke-test `import bitsandbytes` in CI before training jobs"],"tags":["bitsandbytes","dependency","quantization","pytorch-lightning"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}