Environment:Bitsandbytes foundation Bitsandbytes Build From Source Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Build_System |
| Last Updated | 2026-02-07 13:00 GMT |
Overview
Build environment for compiling bitsandbytes from source, requiring CMake 3.22.1+, a C++17 compiler, and the target backend toolkit (CUDA 11.8-13.x, ROCm 6.1+, or XPU SYCL).
Description
This environment defines the build-time requirements for compiling the bitsandbytes native C++/CUDA library from source. The build system uses CMake via scikit-build-core and supports multiple compute backends: CPU, CUDA, HIP (ROCm), MPS (macOS), and XPU (Intel). Each backend has specific compiler and toolkit requirements. The build produces a shared library (libbitsandbytes_{backend}{version}.so) that is loaded at runtime by the Python package.
Usage
Use this environment when pre-compiled wheels are unavailable for your platform, CUDA version, or when you need to build with custom options. This is required when your CUDA version is not among the pre-compiled binaries shipped with the package, or when targeting ROCm/XPU backends.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, Windows, macOS (MPS backend only) | CUDA/HIP not supported on macOS |
| CMake | >= 3.22.1 | CMake < 3.23.0 requires manual CUDA architecture detection |
| C++ Compiler | C++17 support required | GCC 9+, Clang 10+, or MSVC 2019+ |
| CUDA Toolkit | 11.8 to 13.x (for CUDA backend) | CUDA < 11.8 and >= 14.0 produce fatal CMake errors |
| ROCm Toolkit | 6.1+ (for HIP backend) | hipBLASLt unavailable before ROCm 6.1 |
| macOS | Deployment target 14.0+ (for MPS backend) | MPS is the only supported macOS backend |
Dependencies
Build System
- `scikit-build-core`
- `setuptools` >= 77.0.3
- `trove-classifiers` >= 2025.8.6.13
- `cmake` >= 3.22.1
Backend Toolkits
- CUDA: NVIDIA CUDA Toolkit 11.8-13.x with nvcc compiler
- ROCm: AMD ROCm 6.1+ with hipcc compiler and `ROCM_PATH` (defaults to `/opt/rocm`)
- XPU: Intel oneAPI with SYCL compiler
- CPU: No additional toolkit required (uses AVX2/AVX512 if available on x86_64)
Credentials
- `BNB_SKIP_CMAKE`: Set to "1", "true", or "yes" to skip the CMake build step during `pip install`.
- `ROCM_PATH`: Path to ROCm installation for HIP builds (defaults to `/opt/rocm`).
- `CUDA_VERSION`: Optional CMake variable to specify the CUDA version explicitly.
Quick Install
# Build for CUDA
cmake -DCOMPUTE_BACKEND=cuda -S .
make
# Build for ROCm
cmake -DCOMPUTE_BACKEND=hip -S .
make
# Build for CPU only
cmake -DCOMPUTE_BACKEND=cpu -S .
make
# Skip CMake during pip install (if library is pre-built)
BNB_SKIP_CMAKE=1 pip install .
Code Evidence
CUDA version validation from `CMakeLists.txt:125-129`:
if(CMAKE_CUDA_COMPILER_VERSION VERSION_LESS "11.8")
message(FATAL_ERROR "CUDA Version < 11.8 is not supported")
elseif(CMAKE_CUDA_COMPILER_VERSION VERSION_GREATER_EQUAL "14.0")
message(FATAL_ERROR "CUDA Version > 13 is not supported")
endif()
Platform restrictions from `CMakeLists.txt:47-67`:
if(${COMPUTE_BACKEND} STREQUAL "cuda")
if(APPLE)
message(FATAL_ERROR "CUDA is not supported on macOS" )
endif()
elseif(${COMPUTE_BACKEND} STREQUAL "hip")
if(APPLE)
message(FATAL_ERROR "HIP is not supported on macOS" )
endif()
elseif(${COMPUTE_BACKEND} STREQUAL "mps")
if(NOT APPLE)
message(FATAL_ERROR "MPS is only supported on macOS" )
endif()
Build skip option from `setup.py:22`:
if os.environ.get("BNB_SKIP_CMAKE", "").lower() not in ("1", "true", "yes"):
# proceed with CMake build
Supported CUDA architectures from `CMakeLists.txt:135-143`:
if(CMAKE_CUDA_COMPILER_VERSION VERSION_GREATER_EQUAL "13.0")
list(APPEND CMAKE_CUDA_ARCHITECTURES_ALL 75 80 86 87 88 89 90 100 103 110 120 121)
else()
set(CMAKE_CUDA_ARCHITECTURES_ALL 50 52 53 60 61 62 70 72 75 80 86 87 89 90)
endif()
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `FATAL_ERROR "CUDA Version < 11.8 is not supported"` | CUDA toolkit too old | Upgrade to CUDA 11.8+ |
| `FATAL_ERROR "CUDA Version > 13 is not supported"` | CUDA toolkit too new for current bitsandbytes | Wait for bitsandbytes update or use compatible CUDA version |
| `FATAL_ERROR "CUDA is not supported on macOS"` | Attempting CUDA build on Apple hardware | Use `COMPUTE_BACKEND=mps` or `COMPUTE_BACKEND=cpu` |
| `FATAL_ERROR "MPS is only supported on macOS"` | Attempting MPS build on non-Apple system | Use `COMPUTE_BACKEND=cuda`, `hip`, or `cpu` |
Compatibility Notes
- CUDA 13.0+: Drops support for architectures older than Turing (SM75). Only SM75+ supported.
- CUDA 12.8+: Adds Blackwell (SM100, SM101, SM120, SM121) architecture support.
- ROCm HIP < 6.1: Compiles with `NO_HIPBLASLT` flag; hipBLASLt features unavailable.
- CPU backend: Uses AVX2 and FMA instructions on x86_64. AVX512F and AVX512BF16 used when available. ARM (aarch64) support is noted as a TODO.
- macOS: Only CPU and MPS backends supported. Deployment target is macOS 14.0+.