Lightning-AI/pytorch-lightning · error · ModuleNotFoundError

str(_BITSANDBYTES_AVAILABLE)

Error message

str(_BITSANDBYTES_AVAILABLE)

What it means

_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.

Source

Thrown at src/lightning/fabric/plugins/precision/bitsandbytes.py:206

                quant_state=quant_state,
                blocksize=param.blocksize,
                compress_statistics=param.compress_statistics,
                quant_type=param.quant_type,
                quant_storage=param.quant_storage,
                module=param.module,
                bnb_quantized=param.bnb_quantized,
            )
        return torch.nn.Parameter(data, requires_grad=data.requires_grad)
    param.data = data
    if isinstance(param, bnb.nn.Params4bit):
        param.quant_state = quant_state
    return cast(torch.nn.Parameter, param)


@functools.lru_cache(maxsize=1)
def _import_bitsandbytes() -> ModuleType:
    if not _BITSANDBYTES_AVAILABLE:
        raise ModuleNotFoundError(str(_BITSANDBYTES_AVAILABLE))
    # configuration for bitsandbytes before import
    nowelcome_set = "BITSANDBYTES_NOWELCOME" in os.environ
    if not nowelcome_set:
        os.environ["BITSANDBYTES_NOWELCOME"] = "1"
    warnings.filterwarnings("ignore", message=r".*bitsandbytes was compiled without GPU support.*")
    warnings.filterwarnings(
        "ignore", message=r"MatMul8bitLt: inputs will be cast from .* to float16 during quantization"
    )
    import bitsandbytes as bnb

    if not nowelcome_set:
        del os.environ["BITSANDBYTES_NOWELCOME"]

    class _Linear8bitLt(bnb.nn.Linear8bitLt):
        """Wraps `bnb.nn.Linear8bitLt` and enables instantiation directly on the device and re-quantizaton when loading
        the state dict."""

        def __init__(self, *args: Any, device: Optional[_DEVICE] = None, threshold: float = 6.0, **kwargs: Any) -> None:

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Install bitsandbytes: `pip install bitsandbytes` (or `pip install lightning[bitsandbytes]`)
2. Verify `python -c "import bitsandbytes"` and resolve any underlying ImportError (CUDA toolkit, wheel version)
3. On unsupported platforms, remove the BitsandbytesPrecision plugin

Example fix

# before
fabric = Fabric(plugins=BitsandbytesPrecision(mode="nf4"))  # ModuleNotFoundError

# after
# pip install bitsandbytes
fabric = Fabric(plugins=BitsandbytesPrecision(mode="nf4"))

from lightning.fabric.plugins.precision.bitsandbytes import _BITSANDBYTES_AVAILABLE
if not _BITSANDBYTES_AVAILABLE:
    raise SystemExit("bitsandbytes missing: pip install bitsandbytes")

def bitsandbytes_ready() -> bool:
    from lightning.fabric.plugins.precision.bitsandbytes import _BITSANDBYTES_AVAILABLE
    return bool(_BITSANDBYTES_AVAILABLE)

try:
    import bitsandbytes  # noqa
    HAS_BNB = True
except ImportError:
    HAS_BNB = False
plugins = [BitsandbytesPrecision(mode="nf4")] if HAS_BNB else []

When it happens

Trigger: Using BitsandbytesPrecision without bitsandbytes installed, or with a bitsandbytes install that fails to import (broken CUDA libs, wrong wheel for the platform).

Common situations: Forgetting `pip install bitsandbytes`, CPU-only environments where bitsandbytes can't load, or CUDA/bitsandbytes version mismatches producing an ImportError at import time.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• {mode!r} only works with `dtype=torch.float16`, but you chos
• You are using the bitsandbytes precision plugin, but your mo
• Instantiating your model under the `init_module` context man
• Bitsandbytes is only supported on CUDA GPUs.
• str(_XLA_AVAILABLE)

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/8fac3b3431e6d5bf. Report an issue: GitHub.