【Bug已解决】PyTorch torch cant find CUDA: version libcublasLt.so.11 not defined in file libcublasLt.so.11 解决方案问题描述在配置 PyTorch GPU 环境时很多开发者会遇到一个令人沮丧的动态链接库错误version libcublasLt.so.11 not defined in file libcublasLt.so.11 with link time reference或者类似的变体ImportError: libcublasLt.so.11: cannot open shared object file: No such file or directory OSError: /usr/local/lib/python3.8/site-packages/torch/lib/libtorch_cuda.so: undefined symbol: libcublasLt.so.11 RuntimeError: CUDA error: version libcublasLt.so.11 not defined in file libcublasLt.so.11这个错误表明 PyTorch 在运行时无法正确找到或加载 CUDA 的 cuBLAS 库特别是libcublasLt.so.11。cuBLAS 是 NVIDIA 提供的线性代数库PyTorch 依赖它来执行 GPU 上的矩阵运算。当系统中的 CUDA 版本与 PyTorch 编译时使用的 CUDA 版本不匹配或者 CUDA 库文件路径未正确配置时就会出现这个错误。该问题常见于以下场景系统安装了多个 CUDA 版本如 CUDA 10.2 和 CUDA 11.0 共存使用 conda 安装 PyTorch 但系统 PATH 中有其他 CUDA 版本NVIDIA 驱动版本过旧不支持所需的 CUDA 版本Docker 容器中 CUDA 运行时库缺失从源码编译 PyTorch 时 CUDA 配置错误错误复现以下命令和代码可以复现这个错误import torch # 尝试检测 CUDA 是否可用 print(fPyTorch 版本: {torch.__version__}) print(fCUDA 版本 (编译时): {torch.version.cuda}) # 尝试使用 GPU try: print(fCUDA 是否可用: {torch.cuda.is_available()}) except Exception as e: print(fCUDA 检测失败: {e}) # 可能输出: RuntimeError: CUDA error: version libcublasLt.so.11 not defined... # 尝试创建 CUDA 张量 try: x torch.randn(3, 3).cuda() print(fCUDA 张量创建成功: {x}) except Exception as e: print(fCUDA 张量创建失败: {e}) # 可能输出: RuntimeError: CUDA error: version libcublasLt.so.11 not defined...在终端中你也可以通过以下命令检查问题# 检查 PyTorch 链接的 CUDA 库 ldd /path/to/torch/lib/libtorch_cuda.so | grep cublas # 可能输出: # libcublas.so.11 not found # libcublasLt.so.11 not found # 或者: # libcublasLt.so.11 /usr/local/cuda-10.2/lib64/libcublasLt.so.11 (版本不匹配) # 检查系统 CUDA 版本 nvcc --version nvidia-smi # 检查环境变量 echo $LD_LIBRARY_PATH echo $CUDA_HOME根因分析1. CUDA 版本不匹配PyTorch 的每个版本都是针对特定的 CUDA 版本编译的。例如PyTorch 1.9.0cu111 是针对 CUDA 11.1 编译的它需要libcublasLt.so.11。如果系统安装的是 CUDA 10.2则只有libcublasLt.so.10找不到.so.11版本。PyTorch 编译时 CUDA 版本 - 需要的 cuBLAS 库 CUDA 10.2 - libcublasLt.so.10 CUDA 11.0 - libcublasLt.so.11 CUDA 11.1 - libcublasLt.so.11 CUDA 11.3 - libcublasLt.so.11 CUDA 12.0 - libcublasLt.so.122. 库文件路径未配置即使安装了正确版本的 CUDA如果LD_LIBRARY_PATH环境变量没有包含 CUDA 库的路径动态链接器也找不到libcublasLt.so。3. 多 CUDA 版本冲突当系统安装了多个 CUDA 版本时LD_LIBRARY_PATH可能指向错误的版本。例如系统同时安装了 CUDA 10.2 和 CUDA 11.0但LD_LIBRARY_PATH优先指向 CUDA 10.2 的库目录导致 PyTorch需要 CUDA 11加载了错误版本的 cuBLAS。4. conda 环境中的 CUDA 库冲突使用 conda 安装 PyTorch 时conda 会安装所需的 CUDA 运行时库到 conda 环境中。但如果系统也安装了 CUDA且系统 CUDA 的路径在LD_LIBRARY_PATH中优先级更高就会覆盖 conda 环境中的库导致版本冲突。5. NVIDIA 驱动版本不兼容CUDA 11.x 需要 NVIDIA 驱动版本 450.36.06Linux或 456.38Windows。如果驱动版本过旧即使 CUDA 工具包安装正确也无法正常使用。6. Docker 容器中缺少 CUDA 运行时在 Docker 中运行 PyTorch 时如果基础镜像不包含 CUDA 运行时库如使用普通的 Python 镜像而非nvidia/cuda镜像就会缺少 cuBLAS 库。解决方案方案一安装匹配的 CUDA 版本和 PyTorch最根本的解决方案是确保 PyTorch 版本与系统 CUDA 版本匹配。首先检查系统状态# 检查 NVIDIA 驱动版本 nvidia-smi # 输出示例: # ----------------------------------------------------------------------------- # | NVIDIA-SMI 460.32.03 Driver Version: 460.32.03 CUDA Version: 11.2 | # ----------------------------------------------------------------------------- # 检查已安装的 CUDA 工具包 ls /usr/local/ | grep cuda # 可能输出: cuda cuda-10.2 cuda-11.0 cuda-11.2 # 检查当前 CUDA 路径 which nvcc nvcc --version然后根据系统 CUDA 版本安装对应的 PyTorch# 如果系统 CUDA 版本是 11.0 pip install torch1.9.0cu110 torchvision0.10.0cu110 -f https://download.pytorch.org/whl/torch_stable.html # 如果系统 CUDA 版本是 11.1 pip install torch1.9.0cu111 torchvision0.10.0cu111 -f https://download.pytorch.org/whl/torch_stable.html # 如果系统 CUDA 版本是 11.3 pip install torch1.10.0cu113 torchvision0.11.1cu113 -f https://download.pytorch.org/whl/torch_stable.html # 使用 conda 安装推荐conda 会自动管理 CUDA 依赖 conda install pytorch torchvision cudatoolkit11.0 -c pytorch方案二配置正确的环境变量确保LD_LIBRARY_PATH包含正确版本的 CUDA 库路径# 设置 CUDA_HOME 和 LD_LIBRARY_PATH # 将以下内容添加到 ~/.bashrc 或 ~/.zshrc # 方法1指向特定 CUDA 版本 export CUDA_HOME/usr/local/cuda-11.0 export LD_LIBRARY_PATH${CUDA_HOME}/lib64:${LD_LIBRARY_PATH} export PATH${CUDA_HOME}/bin:${PATH} # 方法2使用软链接指向默认 CUDA # sudo ln -s /usr/local/cuda-11.0 /usr/local/cuda export CUDA_HOME/usr/local/cuda export LD_LIBRARY_PATH${CUDA_HOME}/lib64:${LD_LIBRARY_PATH} # 使配置生效 source ~/.bashrc验证配置# 检查库文件是否可找到 ldconfig -p | grep cublas # 应输出: # libcublas.so.11 (libc6,x86-64) /usr/local/cuda-11.0/lib64/libcublas.so.11 # libcublasLt.so.11 (libc6,x86-64) /usr/local/cuda-11.0/lib64/libcublasLt.so.11 # 检查 PyTorch 链接 python -c import torch; print(torch.cuda.is_available())方案三使用 conda 管理独立的 CUDA 环境conda 可以安装独立的 CUDA 运行时不依赖系统 CUDA# 创建新的 conda 环境 conda create -n pytorch-gpu python3.8 conda activate pytorch-gpu # 安装 PyTorch 和对应的 CUDA toolkit # conda 会将 CUDA 运行时库安装到 conda 环境中 conda install pytorch torchvision cudatoolkit11.0 -c pytorch # 验证 python -c import torch; print(torch.cuda.is_available()) # 应输出: True # 检查 conda 环境中的 CUDA 库 ls $CONDA_PREFIX/lib/libcublas* # 应输出: libcublas.so libcublas.so.11 libcublasLt.so libcublasLt.so.11方案四使用 Docker 容器使用 NVIDIA 官方的 Docker 镜像可以避免所有 CUDA 环境配置问题# Dockerfile FROM nvidia/cuda:11.0-cudnn8-runtime-ubuntu20.04 # 安装 Python 和 PyTorch RUN apt-get update apt-get install -y python3 python3-pip RUN pip3 install torch1.9.0cu110 torchvision0.10.0cu110 \ -f https://download.pytorch.org/whl/torch_stable.html # 复制项目代码 COPY . /workspace WORKDIR /workspace # 运行命令 CMD [python3, train.py]运行 Docker 容器# 需要 nvidia-docker 或 nvidia-container-toolkit docker run --gpus all -it --rm my-pytorch-image方案五修复动态链接库如果库文件存在但链接不正确可以手动修复# 查找 libcublasLt.so 的实际位置 find / -name libcublasLt.so* 2/dev/null # 可能输出: # /usr/local/cuda-11.0/lib64/libcublasLt.so.11 # /usr/local/cuda-11.0/lib64/libcublasLt.so.11.0.221 # /usr/local/cuda-10.2/lib64/libcublasLt.so.10 # 创建软链接如果缺少 .so.11 链接 sudo ln -s /usr/local/cuda-11.0/lib64/libcublasLt.so.11.0.221 \ /usr/local/cuda-11.0/lib64/libcublasLt.so.11 # 更新动态链接器缓存 sudo ldconfig # 验证 ldconfig -p | grep cublasLt完整修复代码以下是一个完整的 CUDA 环境检测和修复脚本import os import sys import subprocess import re from typing import Optional, Tuple, List class CudaEnvironmentChecker: CUDA 环境检测和诊断工具。 全面检查 PyTorch 与 CUDA 的兼容性。 def __init__(self): self.issues [] self.recommendations [] def run_command(self, cmd: str) - Tuple[bool, str]: 运行 shell 命令并返回结果 try: result subprocess.run( cmd, shellTrue, capture_outputTrue, textTrue, timeout10 ) return True, result.stdout.strip() except Exception as e: return False, str(e) def check_nvidia_driver(self) - Optional[str]: 检查 NVIDIA 驱动版本 success, output self.run_command(nvidia-smi --query-gpudriver_version --formatcsv,noheader) if success and output: driver_version output.split(\n)[0].strip()  print(f[OK] NVIDIA 驱动版本: {driver_version}) # 检查驱动版本是否支持 CUDA 11 parts driver_version.split(.) major, minor int(parts[0]), int(parts[1]) version_num major * 100 minor if version_num 4500: self.issues.append(f驱动版本 {driver_version} 过旧CUDA 11.x 需要驱动 450.36.06) self.recommendations.append(升级 NVIDIA 驱动到最新版本) return driver_version else: self.issues.append(无法检测 NVIDIA 驱动可能未安装驱动或 nvidia-smi 不在 PATH 中) return None def check_cuda_toolkit(self) - Optional[str]: 检查 CUDA 工具包版本 # 检查 nvcc success, output self.run_command(nvcc --version) if success and output: # 解析 CUDA 版本 match re.search(rrelease (\d\.\d), output) if match: cuda_version match.group(1) print(f[OK] CUDA 工具包版本: {cuda_version}) return cuda_version # 检查 CUDA_HOME cuda_home os.environ.get(CUDA_HOME, /usr/local/cuda) if os.path.exists(cuda_home): version_file os.path.join(cuda_home, version.json) if os.path.exists(version_file): import json with open(version_file) as f: data json.load(f) cuda_version data.get(cuda, {}).get(version, unknown) print(f[OK] CUDA 工具包版本 (from version.json): {cuda_version}) return cuda_version print([WARN] 无法检测 CUDA 工具包版本) return None def check_cublas_library(self) - List[str]: 检查 cuBLAS 库文件 # 查找 libcublasLt.so success, output self.run_command(find /usr/local -name libcublasLt.so* 2/dev/null) found_libs output.split(\n) if success and output else [] # 也检查 conda 环境 conda_prefix os.environ.get(CONDA_PREFIX, ) if conda_prefix: success2, output2 self.run_command(ffind {conda_prefix} -name libcublasLt.so* 2/dev/null) if success2 and output2: found_libs.extend(output2.split(\n)) found_libs [lib for lib in found_libs if lib] if found_libs: print(f[OK] 找到 cuBLAS 库文件:) for lib in found_libs: print(f {lib}) else: self.issues.append(未找到 libcublasLt.so 库文件) self.recommendations.append(安装 CUDA 工具包或使用 conda 安装 cudatoolkit) return found_libs def check_ld_library_path(self) - str: 检查 LD_LIBRARY_PATH ld_path os.environ.get(LD_LIBRARY_PATH, ) print(f[INFO] LD_LIBRARY_PATH: {ld_path if ld_path else (未设置)}) cuda_home os.environ.get(CUDA_HOME, /usr/local/cuda) cuda_lib os.path.join(cuda_home, lib64) if cuda_lib not in ld_path: self.issues.append(fLD_LIBRARY_PATH 未包含 CUDA 库路径: {cuda_lib}) self.recommendations.append(f添加: export LD_LIBRARY_PATH{cuda_lib}:$LD_LIBRARY_PATH) return ld_path def check_pytorch_cuda(self) - Tuple[bool, str]: 检查 PyTorch CUDA 支持 try: import torch pytorch_version torch.__version__ compiled_cuda torch.version.cuda print(f[OK] PyTorch 版本: {pytorch_version}) print(f[OK] PyTorch 编译时 CUDA 版本: {compiled_cuda}) # 尝试检测 CUDA 可用性 try: available torch.cuda.is_available() print(f[OK] CUDA 是否可用: {available}) if available: device_name torch.cuda.get_device_name(0) print(f[OK] GPU 设备: {device_name}) return True, pytorch_version except Exception as e: self.issues.append(fPyTorch CUDA 检测失败: {e}) if libcublasLt in str(e): self.recommendations.append( cuBLAS 库版本不匹配请安装与 PyTorch 编译时 CUDA 版本匹配的 CUDA 工具包 ) return False, pytorch_version except ImportError: self.issues.append(PyTorch 未安装) return False, def check_library_links(self): 检查 PyTorch 库的动态链接 try: import torch torch_lib_dir os.path.join(os.path.dirname(torch.__file__), lib) libtorch_cuda os.path.join(torch_lib_dir, libtorch_cuda.so) if os.path.exists(libtorch_cuda): success, output self.run_command(fldd {libtorch_cuda} | grep cublas) if success and output: print(f[INFO] PyTorch cuBLAS 链接:) for line in output.split(\n): print(f {line}) if not found in output: self.issues.append(PyTorch 的 cuBLAS 依赖未找到) except Exception as e: print(f[WARN] 无法检查库链接: {e}) def run_full_check(self): 运行完整的环境检查 print( * 60) print(CUDA 环境全面诊断) print( * 60) print() print(--- NVIDIA 驱动 ---) self.check_nvidia_driver() print() print(--- CUDA 工具包 ---) self.check_cuda_toolkit() print() print(--- cuBLAS 库 ---) self.check_cublas_library() print() print(--- 环境变量 ---) self.check_ld_library_path() print() print(--- PyTorch ---) self.check_pytorch_cuda() print() print(--- 库链接 ---) self.check_library_links() print() # 输出诊断结果 print( * 60) print(诊断结果) print( * 60) if not self.issues: print(未发现问题CUDA 环境配置正确。) else: print(f发现 {len(self.issues)} 个问题:) for i, issue in enumerate(self.issues, 1): print(f {i}. {issue}) print(f\n建议修复方案:) for i, rec in enumerate(self.recommendations, 1): print(f {i}. {rec}) print() print( * 60) return len(self.issues) 0 class CudaEnvFixer: CUDA 环境修复工具。 提供自动修复建议和脚本生成。 staticmethod def generate_fix_script(pytorch_cuda_version: str 11.0) - str: 生成修复脚本。 Args: pytorch_cuda_version: PyTorch 编译时的 CUDA 版本 Returns: 修复脚本内容 major_version pytorch_cuda_version.split(.)[0] script f#!/bin/bash # CUDA 环境修复脚本 # 目标 CUDA 版本: {pytorch_cuda_version} echo CUDA 环境修复脚本 # 1. 设置 CUDA 环境变量 CUDA_VERSION{pytorch_cuda_version} CUDA_MAJOR{major_version} CUDA_HOME/usr/local/cuda-$CUDA_VERSION if [ ! -d $CUDA_HOME ]; then echo 错误: CUDA $CUDA_VERSION 未安装在 $CUDA_HOME echo 请从 https://developer.nvidia.com/cuda-downloads 下载安装 exit 1 fi # 2. 设置环境变量 export CUDA_HOME export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH export PATH$CUDA_HOME/bin:$PATH echo 已设置环境变量: echo CUDA_HOME$CUDA_HOME echo LD_LIBRARY_PATH 包含 $CUDA_HOME/lib64 # 3. 更新动态链接器缓存 echo 更新 ldconfig... sudo ldconfig # 4. 验证 echo 验证 cuBLAS 库... ldconfig -p | grep cublasLt # 5. 测试 PyTorch echo 测试 PyTorch CUDA... python -c import torch; print(CUDA available:, torch.cuda.is_available()) echo 修复完成 return script staticmethod def generate_conda_install_script(pytorch_version: str 1.9.0, cuda_version: str 11.0) - str: 生成 conda 安装脚本 script f#!/bin/bash # 使用 conda 安装 PyTorch CUDA echo Conda 安装 PyTorch (CUDA {cuda_version}) # 创建新环境 conda create -n pytorch-gpu python3.8 -y conda activate pytorch-gpu # 安装 PyTorch conda install pytorch{pytorch_version} torchvision cudatoolkit{cuda_version} -c pytorch -y # 验证 python -c import torch; print(PyTorch:, torch.__version__); print(CUDA:, torch.cuda.is_available()) echo 安装完成 return script staticmethod def generate_dockerfile(cuda_version: str 11.0, pytorch_version: str 1.9.0) - str: 生成 Dockerfile cudnn_version 8 if cuda_version.startswith(11) else 7 dockerfile f# PyTorch GPU Docker 镜像 FROM nvidia/cuda:{cuda_version}-cudnn{cudnn_version}-runtime-ubuntu20.04 ENV DEBIAN_FRONTENDnoninteractive # 安装 Python RUN apt-get update apt-get install -y \\ python3 python3-pip python3-dev \\ rm -rf /var/lib/apt/lists/* # 安装 PyTorch RUN pip3 install torch{pytorch_version}cu{cuda_version.replace(.,)} \\ -f https://download.pytorch.org/whl/torch_stable.html # 设置工作目录 WORKDIR /workspace # 默认命令 CMD [python3] return dockerfile def verify_cuda_setup(): 验证 CUDA 环境是否正确配置。 运行一系列 GPU 操作测试。 print(\n * 60) print(CUDA 功能验证测试) print( * 60) try: import torch except ImportError: print(PyTorch 未安装跳过验证。) return False if not torch.cuda.is_available(): print(CUDA 不可用跳过 GPU 测试。) return False print(fPyTorch 版本: {torch.__version__}) print(fCUDA 版本: {torch.version.cuda}) print(fGPU 设备: {torch.cuda.get_device_name(0)}) print(fGPU 数量: {torch.cuda.device_count()}) # 测试1: 基本张量操作 print(\n--- 测试1: 基本张量操作 ---) x torch.randn(100, 100).cuda() y torch.randn(100, 100).cuda() z torch.mm(x, y) print(f矩阵乘法结果形状: {z.shape}) print(f结果在 GPU 上: {z.is_cuda}) print(测试1通过) # 测试2: 自动微分 print(\n--- 测试2: 自动微分 ---) w torch.randn(50, 100, requires_gradTrue, devicecuda) b torch.randn(50, requires_gradTrue, devicecuda) inp torch.randn(100, 100, devicecuda) out torch.mm(w, inp) b.unsqueeze(1) loss out.sum() loss.backward() print(f梯度计算完成, w.grad 形状: {w.grad.shape}) print(测试2通过) # 测试3: cuBLAS 验证 print(\n--- 测试3: cuBLAS 验证 ---) # cuBLAS 用于矩阵乘法如果 cuBLAS 有问题mm 会失败 large_x torch.randn(2000, 2000, devicecuda) large_y torch.randn(2000, 2000, devicecuda) large_z torch.mm(large_x, large_y) print(f大矩阵乘法完成, 形状: {large_z.shape}) print(测试3通过 (cuBLAS 正常工作)) # 测试4: GPU 内存管理 print(\n--- 测试4: GPU 内存管理 ---) initial_mem torch.cuda.memory_allocated() temp torch.randn(1000, 1000, devicecuda) allocated_mem torch.cuda.memory_allocated() del temp torch.cuda.empty_cache() freed_mem torch.cuda.memory_allocated() print(f初始内存: {initial_mem / 1024**2:.1f} MB) print(f分配后: {allocated_mem / 1024**2:.1f} MB) print(f释放后: {freed_mem / 1024**2:.1f} MB) print(测试4通过) print(\n * 60) print(所有测试通过CUDA 环境配置正确。) print( * 60) return True if __name__ __main__: # 运行全面诊断 checker CudaEnvironmentChecker() is_healthy checker.run_full_check() if not is_healthy: print(\n生成修复方案...) fixer CudaEnvFixer() # 生成修复脚本 fix_script fixer.generate_fix_script(11.0) print(\n--- 修复脚本 ---) print(fix_script) # 生成 conda 安装脚本 conda_script fixer.generate_conda_install_script() print(\n--- Conda 安装脚本 ---) print(conda_script) # 生成 Dockerfile dockerfile fixer.generate_dockerfile() print(\n--- Dockerfile ---) print(dockerfile) else: print(\nCUDA 环境正常运行功能验证...) verify_cuda_setup()常见陷阱与注意事项1. nvidia-smi 显示的 CUDA 版本不等于已安装的 CUDA 工具包版本nvidia-smi显示的是驱动支持的最高 CUDA 版本而非实际安装的 CUDA 工具包版本。实际安装的 CUDA 版本需要通过nvcc --version查看。这两者经常不一致导致混淆。2. conda 和 pip 混合安装的冲突不要在同一环境中混合使用 conda 和 pip 安装 PyTorch。conda 安装的 PyTorch 自带 CUDA 运行时库而 pip 安装的 PyTorch 依赖系统 CUDA。混装会导致库冲突。3. LD_LIBRARY_PATH 的优先级LD_LIBRARY_PATH中靠前的路径优先级更高。如果系统 CUDA 路径在 conda 环境路径之前会覆盖 conda 的 CUDA 库。确保 conda 环境的库路径优先# 正确conda 路径在前 export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH4. Docker 中的 GPU 支持在 Docker 中使用 GPU 需要安装nvidia-container-toolkit并在运行时使用--gpus all参数。仅安装 NVIDIA 驱动是不够的。5. 升级 PyTorch 后的残留文件升级 PyTorch 版本后旧的.so文件可能残留在 site-packages 中。建议先完全卸载再安装pip uninstall torch torchvision -y pip cache purge pip install torch torchvision6. WSL2 中的 CUDA 配置在 Windows Subsystem for Linux 2 (WSL2) 中使用 CUDA 时不需要在 WSL 内安装 NVIDIA 驱动驱动安装在 Windows 宿主机上。只需安装 CUDA 工具包和 PyTorch 即可。总结libcublasLt.so.11 not defined错误的本质是 CUDA 版本不匹配或库路径配置错误。解决此问题的核心步骤如下诊断环境使用nvidia-smi、nvcc --version和ldd命令全面检查 CUDA 环境。匹配版本确保 PyTorch 编译时的 CUDA 版本与系统安装的 CUDA 版本一致。配置路径正确设置CUDA_HOME和LD_LIBRARY_PATH环境变量。使用 conda推荐使用 conda 安装 PyTorch它自带 CUDA 运行时避免系统冲突。使用 Docker对于生产环境使用 NVIDIA 官方 Docker 镜像是最可靠的方案。验证安装运行 GPU 操作测试确保 cuBLAS 正常工作。通过系统性地诊断和修复可以彻底解决 CUDA 库找不到的问题让 PyTorch 在 GPU 上稳定运行。