RuntimeError: 🚨 CUDA SETUP ERROR: Missing dependency: libnvJitLink.so.13 🚨

快速结论：该报错通常出现在 Google Colab 环境中，当用户安装 bitsandbytes 并升级 PyTorch 到 2.11.0（默认 CUDA 13.0 构建）时，系统缺少 libnvJitLink.so.13 动态库文件。优先排查是否已安装 nvidia-nvjitlink-cu13 包，或确认 CUDA 版本是否已从 12.x 切换到 13.x。

问题场景

用户在 Google Colab 上运行 bitsandbytes 以支持 Qwen 模型时触发。具体操作为安装 bitsandbytes v0.49.2 后执行 !python -m bitsandbytes，同时 PyTorch 从 2.10.0+cu128 升级至 2.11.0+cu130。

报错原文

bitsandbytes library load error: libnvJitLink.so.13: cannot open shared object file: No such file or directory
Traceback (most recent call last):
  File "/usr/local/lib/python3.12/dist-packages/bitsandbytes/cextension.py", line 320, in <module>
    lib = get_native_library()
          ^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/dist-packages/bitsandbytes/cextension.py", line 298, in get_native_library
    dll = ct.cdll.LoadLibrary(str(binary_path))
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/ctypes/__init__.py", line 460, in LoadLibrary
    return self._dlltype(name)
           ^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/ctypes/__init__.py", line 379, in __init__
    self._handle = _dlopen(self._name, mode)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: libnvJitLink.so.13: cannot open shared object file: No such file or directory
=================== bitsandbytes v0.49.2 ===================
Platform: Linux-6.6.113+-x86_64-with-glibc2.35
  libc: glibc-2.35
Python: 3.12.13
PyTorch: 2.11.0+cu130
  CUDA: 13.0
  HIP: N/A
  XPU: N/A
Related packages:
  accelerate: 1.13.0
  diffusers: 0.37.0
  numpy: 2.0.2
  pip: 24.1.2
  peft: 0.18.1
  safetensors: 0.7.0
  transformers: 5.3.0
  triton: 3.6.0
  trl: not found

原因分析

可能原因：PyTorch 2.11.0 默认安装 CUDA 13.0 构建（+cu130），而 Google Colab 预装的 PyTorch 2.10.0+cu128（CUDA 12.x 构建）在升级过程中，其依赖的 CUDA 12.x 版本库（如 nvidia-nvjitlink-cu12）被保留，但 CUDA 13.0 所需的 libnvJitLink.so.13 未自动提供，导致 bitsandbytes 加载失败。此外，CUDA 13.0 中该库的文件路径与 CUDA 12.x 不同：

CUDA 12.x 路径示例：~/.local/lib/python3.12/site-packages/nvidia/nvjitlink/lib/libnvJitLink.so.12
CUDA 13.x 路径示例：~/.local/lib/python3.12/site-packages/nvidia/cu13/lib/libnvJitLink.so.13

因此，环境变量 LD_LIBRARY_PATH 可能未包含此新路径。

环境排查

Python 版本：3.12.13
PyTorch 版本：2.11.0+cu130
bitsandbytes 版本：0.49.2
CUDA 版本：13.0
显卡算力：Compute Capability 7.5（如 Tesla T4）
Google Colab 预装包中 nvidia-nvjitlink-cu12 可能残留

解决步骤

解决方案一（推荐优先尝试）：降级 PyTorch 到 CUDA 12.8 构建，避免 CUDA 13 依赖问题。
在 Colab 中执行：

!pip uninstall -y torch torchvision torchaudio
!pip install -U \
  "torch==2.11.0" \
  "torchvision==0.26.0" \
  "torchaudio==2.11.0" \
  --index-url https://download.pytorch.org/whl/cu128

解决方案二：卸载残留的 CUDA 12 依赖。
执行：
```
!pip uninstall -y nvidia-nvjitlink-cu12
```
注意：此方法可能无法完全解决其他潜在冲突，需后续测试。
解决方案三：保持 PyTorch 2.10.0+cu128 不升级，即在 pip 安装时指定 torch==2.10.0。

解决方案四（手动修复路径）：如果已安装 CUDA 13 构建，可搜索并添加 libnvJitLink.so.13 所在目录到 LD_LIBRARY_PATH。以下为 Colab 适用的自动修复代码（此方案仅为推测，基于社区代码调整，非官方保证）：

import os
import glob
import subprocess

# Step 1: 搜索 libnvJitLink.so.13
search_paths = [
    "/usr/local/lib/python*/dist-packages/nvidia/**/libnvJitLink.so.13",
    "/usr/local/lib/python*/site-packages/nvidia/**/libnvJitLink.so.13",
    "/root/.local/lib/python*/site-packages/nvidia/**/libnvJitLink.so.13",
]

found_paths = []
for pattern in search_paths:
    found_paths.extend(glob.glob(pattern, recursive=True))

try:
    result = subprocess.run(
        ["find", "/usr/local", "-name", "libnvJitLink.so.13"],
        capture_output=True, text=True, timeout=10
    )
    if result.stdout.strip():
        found_paths.extend(result.stdout.strip().split("\n"))
except Exception:
    pass

# Step 2: 添加目录到 LD_LIBRARY_PATH
if found_paths:
    lib_dir = os.path.dirname(found_paths[0])
    old_ld = os.environ.get("LD_LIBRARY_PATH", "")
    os.environ["LD_LIBRARY_PATH"] = f"{lib_dir}:{old_ld}" if old_ld else lib_dir
    print(f"✅ Found libnvJitLink.so.13 at: {found_paths[0]}")
    print(f"✅ Added to LD_LIBRARY_PATH: {lib_dir}")
else:
    print("❌ libnvJitLink.so.13 not found. Installing...")
    subprocess.run(["pip", "install", "-q", "nvidia-nvjitlink-cu13"], check=True)
    found_paths = glob.glob(
        "/usr/local/lib/python*/dist-packages/nvidia/**/libnvJitLink.so.13",
        recursive=True
    )
    if found_paths:
        lib_dir = os.path.dirname(found_paths[0])
        os.environ["LD_LIBRARY_PATH"] = f"{lib_dir}:{os.environ.get('LD_LIBRARY_PATH', '')}"
        print(f"✅ Installed and added: {lib_dir}")

# Step 3: 验证 bitsandbytes
print("\n--- bitsandbytes diagnostic ---")
subprocess.run(["python", "-m", "bitsandbytes"])

验证方法

执行 !python -m bitsandbytes，检查输出中是否不再出现 OSError: libnvJitLink.so.13: cannot open shared object file 错误。若成功，应正常显示 bitsandbytes 诊断信息并完成 CUDA 调用测试。

参考来源

bitsandbytes-foundation/bitsandbytes #1905

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

RuntimeError: 🚨 CUDA SETUP ERROR: Missing dependency: libnvJitLink.so.13 🚨