Hugging Face 的 LOGO

Bitsandbytes 文档

安装指南

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

安装指南

欢迎阅读 bitsandbytes 库的安装指南！本文档提供了在各种平台和硬件配置上安装 bitsandbytes 的分步说明。该库主要支持基于 CUDA 的 GPU，但团队正在积极致力于支持其他后端，如 CPU、AMD ROCm、Intel XPU 和 Gaudi HPU。

目录

CUDA

bitsandbytes 目前支持具有计算能力 5.0+ 的 NVIDIA GPU。该库可以在 Windows 上使用最低为 11.6 版本的 CUDA Toolkit 构建，在 Linux 上为 11.4 版本。

特性 所需计算能力 (CC) 硬件要求示例
LLM.int8() 7.5+ 图灵架构 (RTX 20 系列, T4) 或更新的 GPU
8位优化器/量化 5.0+ 麦克斯韦架构 (GTX 900 系列, TITAN X, M40) 或更新的 GPU
NF4/FP4 量化 5.0+ 麦克斯韦架构 (GTX 900 系列, TITAN X, M40) 或更新的 GPU

对麦克斯韦架构 GPU 的支持已弃用，并将在未来版本中移除。为获得最佳效果，建议使用图灵架构或更新的设备。

通过 PyPI 安装

这是最直接且推荐的安装选项。

当前分发的 bitsandbytes 包是使用以下配置构建的

操作系统 CUDA Toolkit 主机编译器 目标
Linux x86-64 11.8 - 12.6 GCC 11.2 sm50, sm60, sm75, sm80, sm86, sm89, sm90
Linux x86-64 12.8 GCC 11.2 sm75, sm80, sm86, sm89, sm90, sm100, sm120
Linux aarch64 11.8 - 12.6 GCC 11.2 sm75, sm80, sm90
Linux aarch64 12.8 GCC 11.2 sm75, sm80, sm90, sm100
Windows x86-64 11.8 - 12.6 MSVC 19.43+ (VS2022) sm50, sm60, sm75, sm80, sm86, sm89, sm90
Windows x86-64 12.8 MSVC 19.43+ (VS2022) sm75, sm80, sm86, sm89, sm90, sm100, sm120

使用 pip 或 uv 安装

pip install bitsandbytes

从源代码编译

不要犹豫，从源代码编译吧！这个过程非常直接且稳定。对于旧版本的 CUDA Toolkit、Linux 发行版或其他不常见的配置，这可能是必需的。

对于 Linux 和 Windows 系统，从源代码编译允许您自定义构建配置。有关详细的平台特定说明，请参见下文（如果您想查看具体细节并探索一些额外选项，请参阅 CMakeLists.txt 文件）。

Linux
Windows

要从源代码编译，您需要安装 CMake >= 3.22.1 和 Python >= 3.9。请确保您已安装 C++ 编译器（gcc、make、头文件等）。建议使用 GCC 9 或更高版本。

例如，在 Ubuntu 上安装编译器和 CMake：

apt-get install -y build-essential cmake

您还应按照 NVIDIA CUDA Linux 安装指南 安装 CUDA Toolkit。我们测试的当前最低支持的 CUDA Toolkit 版本是 11.8。

git clone https://github.com/bitsandbytes-foundation/bitsandbytes.git && cd bitsandbytes/
cmake -DCOMPUTE_BACKEND=cuda -S .
make
pip install -e .   # `-e` for "editable" install, when developing BNB (otherwise leave that out)

如果您安装了多个版本的 CUDA Toolkit，或者它位于非标准位置，请参阅 CMake CUDA 文档了解如何配置 CUDA 编译器。

来自 main 的预览版 Wheels

如果您想在新功能正式发布前就使用它们并帮助我们进行测试，请随时从我们的 CI 直接安装 wheel 包（wheel 链接将保持稳定！）

Linux
Windows
# Note: if you don't want to reinstall our dependencies, append the `--no-deps` flag!

# x86_64 (most users)
pip install --force-reinstall https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_x86_64.whl

# ARM/aarch64
pip install --force-reinstall https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_aarch64.whl

多后端预览

此功能曾作为早期技术预览存在，不建议在生产环境中使用。我们正在将对 AMD 和 Intel 硬件的改进支持整合到主项目中。

我们提供了一个开发分支，作为对 AMD 和 Intel 硬件支持的早期预览。

支持的后端

后端 支持的版本 Python 版本 架构支持 状态
AMD ROCm 6.1+ 3.10+ 最低 CDNA - gfx90a, RDNA - gfx1100 Alpha
Intel CPU v2.4.0+ (ipex) 3.10+ Intel CPU Alpha
英特尔 GPU v2.4.0+ (ipex) 3.10+ 英特尔 GPU 实验性
Ascend NPU 2.1.0+ (torch_npu) 3.10+ Ascend NPU 实验性

对于每个支持的后端，请按照下面相应的说明进行操作

先决条件

要将此预览版的 bitsandbytes 与 transformers 一起使用，请确保安装

pip install "transformers>=4.45.1"
AMD ROCm
Intel XPU

预编译的二进制文件仅为 ROCm 版本 6.1.2/6.2.4/6.3.2 以及 gfx90a、gfx942、gfx1100 GPU 架构构建。在这里找到 pip 安装说明。

其他不支持预编译二进制文件的版本可以使用这些说明进行编译。

ROCm 后端不支持 Windows

如果您想在裸机上安装 ROCm 和 PyTorch，请跳过 Docker 步骤，并参考 ROCm 的官方指南：ROCm 安装概述 和 为 ROCm 安装 PyTorch (wheels 构建的第 3 步可快速安装)。特别注意：请确保为已安装的 ROCm 版本获取相应的 ROCm 特定 PyTorch wheel，例如 https://download.pytorch.org/whl/nightly/rocm6.2/！

# Create a docker container with the ROCm image, which includes ROCm libraries
docker pull rocm/dev-ubuntu-22.04:6.3.4-complete
docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-22.04:6.3.4-complete
apt-get update && apt-get install -y git && cd home

# Install pytorch compatible with above ROCm version
pip install torch --index-url https://download.pytorch.org/whl/rocm6.3/

安装

您可以为每个后端安装预构建的 wheels，或者为自定义配置从源代码编译。

预构建 Wheel 安装 (推荐)

Linux
Windows

此 wheel 为 ROCm 和 Intel XPU 平台提供支持。

# Note, if you don't want to reinstall our dependencies, append the `--no-deps` flag!
pip install --force-reinstall 'https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_multi-backend-refactor/bitsandbytes-0.44.1.dev0-py3-none-manylinux_2_24_x86_64.whl'

从源代码编译

AMD ROCm
Intel CPU + GPU
Ascend NPU

AMD GPU

bitsandbytes 支持从 ROCm 6.1 到 ROCm 6.4。

# Install bitsandbytes from source
# Clone bitsandbytes repo, ROCm backend is currently enabled on multi-backend-refactor branch
git clone -b multi-backend-refactor https://github.com/bitsandbytes-foundation/bitsandbytes.git && cd bitsandbytes/

# Compile & install
apt-get install -y build-essential cmake  # install build tools dependencies, unless present
cmake -DCOMPUTE_BACKEND=hip -S .  # Use -DBNB_ROCM_ARCH="gfx90a;gfx942" to target specific gpu arch
make
pip install -e .   # `-e` for "editable" install, when developing BNB (otherwise leave that out)
< > 在 GitHub 上更新

←bitsandbytes 快速入门→