Hugging Face 的标志

Bitsandbytes 文档

安装指南

Hugging Face's logo
加入 Hugging Face 社区

并获取增强的文档体验

开始使用

安装指南

欢迎来到 bitsandbytes 库的安装指南！本文档提供了在各种平台和硬件配置上安装 bitsandbytes 的分步说明。该库主要支持基于 CUDA 的 GPU，但团队正在积极努力为 AMD ROCm、Intel 和 Apple Silicon 等其他后端启用支持。

有关后端支持和兼容性的高级概述，请参阅 多后端支持 部分。

目录

CUDA

bitsandbytes 目前仅在 CUDA 版本 11.0 - 12.8 的 CUDA GPU 上受支持。但是，正在开发一项多后端工作，目前处于 alpha 阶段。如果您有兴趣提供反馈或测试，请查看下面的多后端部分。

支持的 CUDA 配置

最新版本的分布式 bitsandbytes 包是使用以下配置构建的

操作系统 CUDA 工具包 主机编译器
Linux 11.7 - 12.3 GCC 11.4
12.4 - 12.8 GCC 13.2
Windows 11.7 - 12.8 MSVC 19.42+ (VS2022)

对于 CUDA 系统，请确保您的硬件满足以下要求

特性 最低硬件要求
LLM.int8() NVIDIA Turing (RTX 20 系列，T4) 或更新的 GPU
8 位优化器/量化 NVIDIA Maxwell (GTX 900 系列，TITAN X，M40) 或更新的 GPU *
NF4/FP4 量化 NVIDIA Maxwell (GTX 900 系列，TITAN X，M40) 或更新的 GPU *

bitsandbytes >= 0.45.0 不再支持 Kepler GPU。

对 Maxwell GPU 的支持已弃用，并将在未来的版本中删除。为了获得最佳效果，建议使用 Turing 世代或更新的设备。

pip install bitsandbytes

从最新的主提交 pip 安装预构建 Wheel 包

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

Linux
Windows
# Note, if you don't want to reinstall BNBs dependencies, append the `--no-deps` flag!
pip install --force-reinstall 'https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-0.44.2.dev0-py3-none-manylinux_2_24_x86_64.whl'

从源代码编译

不要犹豫从源代码编译！该过程非常简单且具有弹性。对于较旧的 CUDA 版本或其他不太常见的配置，这可能是必需的，由于软件包大小，我们不支持开箱即用。

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

Linux
Windows

要从源代码编译，您需要安装 CMake >= 3.22.1 和 Python >= 3.9。确保您已安装编译器以编译 C++ (gcc、make、headers 等)。

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

apt-get install -y build-essential cmake

您还应该按照 NVIDIA 的 NVIDIA CUDA Linux 安装指南 安装 CUDA 工具包。当前预期的 CUDA 工具包版本为 11.1+，建议安装 GCC >= 7.3，并且至少需要 GCC >= 6。

如果您使用其他 CUDA 工具包版本，请参阅下表。

CUDA 工具包 GCC
>= 11.4.1 >= 11
>= 12.0 >= 12
>= 12.4 >= 13

现在从源代码安装 bitsandbytes 包，运行以下命令

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 版本或将其安装在非标准位置，请参阅 CMake CUDA 文档，了解如何配置 CUDA 编译器。

PyTorch CUDA 版本

某些 bitsandbytes 功能可能需要比 Conda 和 pip 的 PyTorch 二进制文件当前支持的 CUDA 版本更新的版本。在这种情况下，您应该按照这些说明加载预编译的 bitsandbytes 二进制文件。

  1. 确定您要使用的 CUDA 版本的路径。常见路径包括
  • /usr/local/cuda
  • /usr/local/cuda-XX.X，其中 XX.X 是 CUDA 版本号

然后使用 bitsandbytes 中的此脚本本地安装您需要的 CUDA 版本

wget https://raw.githubusercontent.com/bitsandbytes-foundation/bitsandbytes/main/install_cuda.sh
# Syntax cuda_install CUDA_VERSION INSTALL_PREFIX EXPORT_TO_BASH
#   CUDA_VERSION in {110, 111, 112, 113, 114, 115, 116, 117, 118, 120, 121, 122, 123, 124, 125, 126, 128}
#   EXPORT_TO_BASH in {0, 1} with 0=False and 1=True

# For example, the following installs CUDA 12.6 to ~/local/cuda-12.6 and exports the path to your .bashrc

bash install_cuda.sh 126 ~/local 1
  1. 通过手动覆盖 PyTorch 安装的 CUDA 版本，设置环境变量 BNB_CUDA_VERSION 和 LD_LIBRARY_PATH。

建议将以下行添加到 .bashrc 文件中，使其永久生效。

export BNB_CUDA_VERSION=<VERSION>
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<PATH>

例如，要使用本地安装路径

export BNB_CUDA_VERSION=126
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/YOUR_USERNAME/local/cuda-12.6
  1. 现在，当您使用这些环境变量启动 bitsandbytes 时，PyTorch CUDA 版本将被新的 CUDA 版本（在本例中为版本 12.6）覆盖，并加载不同的 bitsandbytes 库。

多后端支持（Alpha 版本）

此功能目前处于预览阶段，尚未准备好用于生产环境。我们非常欢迎社区就 Apple Silicon 以及其他不太常见的加速器等主题提供反馈、贡献和领导！有关更多信息，请参阅关于多后端支持的本指南。

提供反馈的链接（错误、安装问题、性能结果、请求等）：

ROCm
Intel CPU+GPU
Apple Silicon / Metal (MPS)

多后端重构：Alpha 版本 (仅限 AMD ROCm)

支持的后端

后端 支持的版本 Python 版本 架构支持 状态
AMD ROCm 6.1+ 3.10+ 最低 CDNA - gfx90a，RDNA - gfx1100 Alpha
Apple Silicon (MPS) WIP 3.10+ M1/M2 芯片 计划中
Intel CPU v2.4.0+ (ipex) 3.10+ Intel CPU Alpha
Intel GPU v2.4.0+ (ipex) 3.10+ Intel GPU 实验性
Ascend NPU 2.1.0+ (torch_npu) 3.10+ Ascend NPU 实验性

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

先决条件

要使用 bitsandbytes 非 CUDA 后端，请务必安装

pip install "transformers>=4.45.1"
AMD ROCm
Intel CPU + GPU
Apple Silicon (MPS)

预编译二进制文件仅针对 ROCm 版本 6.1.2/6.2.4/6.3.2 和 gfx90a、gfx942、gfx1100 GPU 架构构建。在此处查找 pip 安装说明。

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

ROCm 后端不支持 Windows；据我们所知，WSL2 也不支持。

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

# Create a docker container with latest ROCm image, which includes ROCm libraries
docker pull rocm/dev-ubuntu-22.04:6.1.2-complete
docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-22.04:6.1.2-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.1/

安装

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

预构建 Wheel 包安装（推荐）

Linux
Windows
Ascend NPU
Mac
# Note, if you don't want to reinstall BNBs 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
Apple Silicon (MPS)

AMD GPU

从 ROCm 6.1 开始，bitsandbytes 得到完全支持（目前为 alpha 版本）。

# 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 上更新

←快速入门 8-位优化器→