Stable Diffusion WebUI 通常依赖 GPU 来加速图像生成，一旦出现以下错误，就意味着 GPU 无法被 PyTorch 正确识别或使用：
RuntimeError: Torch is not able to use GPU本文将从问题背景与含义、环境检查与依赖安装、PyTorch 与 CUDA 兼容性、Stable Diffusion WebUI 配置、以及综合排查流程等角度展开，配以代码示例、Mermaid 图解和详细说明，帮助读者快速定位并解决该错误。
一、问题背景与含义
错误现象
当运行 Stable Diffusion WebUI（如 AUTOMATIC1111、NMKD WebUI 等）时，控制台或浏览器界面报错：RuntimeError: Torch is not able to use GPU导致生成任务只能使用 CPU，速度极慢，甚至无法启动推理。
可能原因
- 显卡驱动或 CUDA 驱动未安装/损坏
- CUDA 与 PyTorch 二进制不匹配
- PyTorch 安装时没有 GPU 支持
- 环境变量未配置，导致 PyTorch 无法找到 CUDA
- 多 CUDA 版本冲突（比如系统同时装了 CUDA 11.7、12.1，但 PyTorch 只支持 11.6）
- 显卡不支持当前 CUDA 版本（DDR 显存不足或计算能力不足）
- WebUI 运行在虚拟环境中，但环境内未安装带 GPU 支持的 PyTorch
“Torch is not able to use GPU” 本质是告诉我们：虽然系统中可能存在 NVIDIA GPU，但在当前 Python 环境中，`torch.cuda.is_available()` 返回 `False`，或者 PyTorch 在加载时检测不到可用的 CUDA 驱动和显卡。
二、环境检查与依赖安装
在正式调试前，务必确认以下基础环境是否正常。
2.1 检查 NVIDIA 驱动与显卡状态
nvidia-smi
# 查看显卡型号、驱动版本、显存占用等 nvidia-smi- 如果能正常输出，说明系统已识别 NVIDIA GPU，请记录 Driver Version、CUDA Version 以及显卡型号（如 GeForce RTX 3070）。
- 如果报
Command 'nvidia-smi' not found或 “NVIDIA-SMI has failed”，则需要先安装或重装 NVIDIA 驱动（见下文）。
lspci | grep -i nvidia（仅限 Linux）
# 查看系统是否检测到 NVIDIA 显卡 lspci | grep -i nvidia- 若能看到类似
VGA compatible controller: NVIDIA Corporation Device ...，表示内核层面已识别显卡。否则须检查物理插槽或 BIOS 设置。
- 若能看到类似
2.2 安装/重装 NVIDIA 驱动（以 Ubuntu 为例）
说明：Windows 用户可直接从 NVIDIA 官网 Download Center 下载对应显卡型号的驱动并安装，略去此节。以下以 Ubuntu 22.04 为示例。
添加 NVIDIA 驱动源
sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt-get update自动识别并安装推荐驱动
sudo ubuntu-drivers autoinstall- 系统会检测显卡型号并安装对应的最低兼容驱动（通常是
nvidia-driver-5xx）。
- 系统会检测显卡型号并安装对应的最低兼容驱动（通常是
手动安装指定版本
# 列出可用驱动 ubuntu-drivers devices # 假设推荐 nvidia-driver-525 sudo apt-get install nvidia-driver-525重启并验证
sudo reboot # 重启后再次运行 nvidia-smi- 如果输出正常，即可进入下一步。
2.3 检查 CUDA Toolkit 是否已安装
nvcc --version
nvcc --version正常输出示例：
nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2022 NVIDIA Corporation Built on Wed_Nov__9_22:50:21_PST_2022 Cuda compilation tools, release 11.7, V11.7.64- 如果
nvcc未找到，则说明尚未安装 CUDA Toolkit，或者未设置环境变量$PATH。可从 NVIDIA 官网下载对应版本 CUDA（推荐与显卡驱动一起选择合适版本）。
检查
/usr/local/cuda软链接ls -l /usr/local | grep cuda- 通常会有
cuda -> cuda-11.7或cuda-12.1的软链接。若无，则需要手动配置。
- 通常会有
环境变量配置（以 bash 为例）
# 在 ~/.bashrc 或 ~/.zshrc 中添加： export PATH=/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH # 使其生效 source ~/.bashrc- 再次验证
nvcc --version即可。
- 再次验证
温馨提示：切勿安装过多不同版本的 CUDA，否则容易导致环境冲突。建议只保留一个常用版本，并在安装 PyTorch 时选择对应该版本二进制包。
三、PyTorch 与 CUDA 兼容性
Stable Diffusion WebUI 中的推理引擎底层是基于 PyTorch，要让 PyTorch 可用 GPU，必须保证：
- 系统安装了支持 GPU 的 PyTorch（含 CUDA 支持）。
- PyTorch 与系统中 CUDA 版本兼容。
- Python 环境中正确指向 GPU 驱动。
3.1 验证 PyTorch 是否支持 GPU
在终端（或 Python REPL）中执行：
python3 - << 'EOF'
import torch
print("PyTorch 版本：", torch.__version__)
print("CUDA 版本（PyTorch 编译时）：", torch.version.cuda)
print("cuDNN 版本：", torch.backends.cudnn.version())
print("是否能使用 GPU：", torch.cuda.is_available())
if torch.cuda.is_available():
print("GPU 设备数量：", torch.cuda.device_count())
print("当前 GPU 名称：", torch.cuda.get_device_name(0))
EOF预期输出示例（正常情况下）：
PyTorch 版本： 2.1.0+cu117
CUDA 版本（PyTorch 编译时）： 11.7
cuDNN 版本： 8600
是否能使用 GPU： True
GPU 设备数量： 1
当前 GPU 名称： NVIDIA GeForce RTX 3070- 若出现
torch.cuda.is_available(): False，表示当前 PyTorch 无法使用 GPU，需重点排查以下内容。 - 若
torch.version.cuda=None，说明安装的 PyTorch 是 CPU-only 版，需要重新安装带 GPU 支持的 PyTorch。
3.2 安装/重装带 GPU 支持的 PyTorch
- 查看官方安装指引
访问 PyTorch 官网 ，在 "Compute Platform" 选择对应的 CUDA 版本（如CUDA 11.7），复制 pip/conda 安装命令。 常见 pip 安装示例
# 以 CUDA 11.7 为例 pip uninstall -y torch torchvision torchaudio pip cache purge pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117cu117对应CUDA 11.7，若系统是CUDA 12.1，则需选择cu121；若是CUDA 11.8，则常见用cu118。- 若要安装最新版 PyTorch 并自动匹配 CUDA，可使用
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu118（根据当前 PyTorch 发布情况调整）。
- 验证安装
再次执行第三节 3.1 中的验证脚本，确认torch.cuda.is_available() == True，且输出的 CUDA 版本应与系统中安装的 CUDA 相同（或兼容）。
四、Stable Diffusion WebUI 配置与调试
不同的 Stable Diffusion WebUI（如 AUTOMATIC1111 、NMKD ）在安装时略有区别，但核心思路一致：确保当前 Python 环境能正确调用 GPU 上的 PyTorch。下面以 AUTOMATIC1111 WebUI 为示例说明常见问题及对应解决方案。
4.1 克隆并初始化 WebUI
# 1. 克隆仓库
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
# 2. 创建 Python 虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate
# 3. 安装依赖（会安装 CPU 版或 GPU 版 PyTorch，取决于自动检测）
# 运行 webui.sh 脚本会触发自动依赖安装
./webui.sh --skip-torch-cuda-test参数
--skip-torch-cuda-test可在安装过程中跳过自动检测，若要手动控制 PyTorch 版本，可预先安装好带 GPU 支持的 PyTorch，如第四节 3.2 中所示，然后再运行./webui.sh --skip-torch-cuda-test --skip-python-deps：# 假设已手动安装好 torch-cu117 ./webui.sh --skip-python-deps --skip-torch-cuda-test这样不会自动重装 PyTorch，而是保留当前环境中的 GPU 版 PyTorch。
4.2 检查 WebUI 启动日志
启动 WebUI 前，先检查当前终端是否位于 venv 中，且 python -c "import torch;print(torch.cuda.is_available())" 为 True。否则 WebUI 会报错：“Torch is not able to use GPU”，具体日志示例：
Fetching: torch==2.1.0+cu117
Installing torch-2.1.0+cu117...
...
Running on local URL: http://127.0.0.1:7860
Traceback (most recent call last):
...
File "modules/timers.py", line 56, in run
cuda = torch.cuda.is_available()
RuntimeError: Torch is not able to use GPU- 当日志包含上述错误时，说明 Python 中的 PyTorch 无法识别 GPU，需返回至第三节进一步排查。
4.3 常见 WebUI GPU 报错场景与解决方案
场景 A：torch.cuda.is_available() 返回 False
原因
- PyTorch 安装的是 CPU 版本（
torch==2.x+cpu）。 - 环境中存在多个 Python，实际使用的 Interpreter 并非虚拟环境。
- 环境变量指向了错误的 CUDA 路径。
- PyTorch 安装的是 CPU 版本（
排查与解决
确认当前使用的 Python
which python which pip python -V pip show torch- 确保
which python指向.../stable-diffusion-webui/venv/bin/python，而非系统全局 Python。 pip show torch输出中若显示torch-2.x+cpu，需重新安装 GPU 版。
- 确保
强制重新安装带 GPU 支持的 PyTorch
pip uninstall -y torch torchvision torchaudio pip cache purge # 以 CUDA 11.7 为例 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117然后再次验证：
python3 - << 'EOF' import torch print("是否可用 GPU：", torch.cuda.is_available()) print("当前 CUDA 版本：", torch.version.cuda) print("显卡名称：", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "无") EOF
检查环境变量
- 确认
$PATH和$LD_LIBRARY_PATH中包含正确的 CUDA 路径（如/usr/local/cuda-11.7/bin、/usr/local/cuda-11.7/lib64）。 若同时安装了多个 CUDA，可通过设置
CUDA_HOME或CUDA_VISIBLE_DEVICES来强制指定：export CUDA_HOME=/usr/local/cuda-11.7 export CUDA_VISIBLE_DEVICES=0 # 只使用 GPU 0
- 确认
场景 B：显卡驱动版本与 CUDA 版本不兼容
原因
- 比如系统安装的是
NVIDIA Driver 470，默认只支持到CUDA 11.4，而 PyTorch 要求CUDA 11.7。 - 驱动过旧导致
CUDA runtime加载失败。
- 比如系统安装的是
排查与解决
查询 Driver 与 CUDA 兼容表
- 访问 NVIDIA CUDA Compatibility 查看对应关系。
升级 NVIDIA 驱动
sudo apt-get update sudo apt-get install --reinstall nvidia-driver-525 sudo reboot- 再次验证
nvidia-smi：Driver Version应 ≥ PyTorch 编译时所需的最小值。
- 再次验证
重新安装或降级 PyTorch
若无法升级驱动，可选择安装支持当前 Drive 版本的 PyTorch，例如：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu116cu116对应CUDA 11.6；如果nvidia-smi中显示 CUDA 版本为11.4，则可尝试cu114二进制（但官方不再提供 cu114，需自行编译）。
场景 C：WebUI 自动安装的 PyTorch 与系统环境不符
原因
- 执行
./webui.sh时，没有指定--skip-torch-cuda-test，结果脚本自动安装了torch-cpu。 - 或者网络环境只让脚本下载到 CPU 版本。
- 执行
排查与解决
- 查看
requirements.txt
打开stable-diffusion-webui/requirements.txt，如果其中包括torch==...+cpu，则说明脚本强制安装了 CPU 版本。 手动修改
webui.sh
将安装 PyTorch 部分注释掉，改为：# 从官方索引安装 GPU 版 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117这样能保证无论脚本如何检查，都使用手动指定的 GPU 版 PyTorch。
使用
--skip-python-deps./webui.sh --skip-python-deps --skip-torch-cuda-test- 在此之前手动安装好 Python 依赖（包括 GPU 版 torch），可避免脚本覆盖。
- 查看
五、综合排查流程图
下面用 Mermaid 图解 展示从发现 “RuntimeError: Torch is not able to use GPU” 到解决问题的完整诊断流程。
flowchart TD
A[启动 WebUI 报错: Torch 无法使用 GPU] --> B{步骤 1: 检查 NVIDIA 驱动}
B --> B1[运行 nvidia-smi]
B1 -->|输出正常| C{步骤 2: 检查 CUDA Toolkit}
B1 -->|报错或无输出| B2[重装或安装 NVIDIA 驱动] --> B1
C --> C1[运行 nvcc --version 或 which nvcc]
C1 -->|输出正常| D{步骤 3: 检查 PyTorch GPU 支持}
C1 -->|无输出| C2[安装/配置 CUDA Toolkit 并设置 PATH/LD_LIBRARY_PATH] --> C1
D --> D1[python3 -c "import torch; print(torch.cuda.is_available())"]
D1 -->|False| D2[确认 Python 虚拟环境与 torch 版本]
D1 -->|True| E[正常使用 GPU，无需继续排查]
D2 --> D3[which python; pip show torch]
D3 -->|torch-cpu| D4[卸载 CPU 版 torch 并安装 GPU 版 torch]
D3 -->|虚拟环境不对| D5[切换到正确的虚拟环境或重建环境]
D4 --> D1
D5 --> D1图解说明：
- 步骤 1（B 节点）：先确认系统层面是否识别到 NVIDIA GPU，否则立即重装驱动。
- 步骤 2（C 节点）：确认 CUDA Toolkit 安装及路径设置，保证
nvcc可以正常调用。- 步骤 3（D 节点）：在 Python 中检查
torch.cuda.is_available()；如果为 False，则进入下一步细化排查。- 若
torch安装的是 CPU 版本，需卸载并改为 GPU 版本。- 若虚拟环境不对，需切换到正确 Python 环境或重建包含 CUDA 支持的环境。
六、案例实战：Ubuntu22.04 + RTX3070 + CUDA11.7
以下示例演示在 Ubuntu22.04 系统中，从零开始安装并调试 Stable Diffusion WebUI，使之在 GPU（GeForce RTX 3070）上正常运行。
6.1 环境概览
- 操作系统：Ubuntu 22.04 LTS
- 显卡型号：NVIDIA GeForce RTX 3070
- NVIDIA 驱动：525.89.02（支持 CUDA 11.7）
- CUDA Toolkit：11.7
- Python：3.10
- PyTorch：2.1.0+cu117
步骤 6.1：安装 NVIDIA 驱动
# 1. 添加 PPA 并更新
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt-get update
# 2. 安装推荐驱动（假设为 525）
sudo apt-get install nvidia-driver-525 -y
# 3. 重启
sudo reboot重启后验证：
nvidia-smi预期输出（关键信息）：
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.89.02 Driver Version: 525.89.02 CUDA Version: 11.7 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| ... ... |
| 0 GeForce RTX 3070 Off | 00000000:01:00.0 Off | |
+-------------------------------+----------------------+----------------------+步骤 6.2：安装 CUDA Toolkit 11.7
在 NVIDIA CUDA 下载页 下载对应版本，或通过 apt-get 安装：
# 安装 CUDA 11.7
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/7fa2af80.pub
sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/ /"
sudo apt-get update
sudo apt-get -y install cuda-11-7
# 设置环境变量（添加到 ~/.bashrc）
echo 'export PATH=/usr/local/cuda-11.7/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.7/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
# 验证 nvcc
nvcc --version预期输出：
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2022 NVIDIA Corporation
Built on Fri_Oct_21_19:27:37_PDT_2022
Cuda compilation tools, release 11.7, V11.7.99
Build cuda_11.7.r11.7/compiler.31294376_0步骤 6.3：创建并激活 Python 虚拟环境
cd ~/projects
python3.10 -m venv sd-webui-env
source sd-webui-env/bin/activate
# 升级 pip
pip install --upgrade pip setuptools步骤 6.4：安装 GPU 版 PyTorch
# 卸载可能已存在的 CPU 版 torch
pip uninstall -y torch torchvision torchaudio
# 安装 PyTorch 2.1.0 + CUDA 11.7
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
# 验证安装
python3 - << 'EOF'
import torch
print("PyTorch 版本：", torch.__version__)
print("CUDA 版本（PyTorch 编译时）：", torch.version.cuda)
print("是否可用 GPU：", torch.cuda.is_available())
if torch.cuda.is_available():
print("GPU 名称：", torch.cuda.get_device_name(0))
EOF预期输出：
PyTorch 版本： 2.1.0+cu117
CUDA 版本（PyTorch 编译时）： 11.7
是否可用 GPU： True
GPU 名称： NVIDIA GeForce RTX 3070步骤 6.5：克隆并安装 Stable Diffusion WebUI
# 克隆仓库
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
# 跳过自动安装 torch，使用已有 GPU 版
./webui.sh --skip-torch-cuda-test --skip-python-deps若发现脚本在安装依赖时报错，可手动执行：
# 安装剩余依赖（除 torch 外） pip install -r requirements.txt- 确保无
torch、torchvision、torchaudio字样再执行./webui.sh --skip-torch-cuda-test。
步骤 6.6：启动 WebUI 并验证
# 启动 WebUI
./webui.sh启动成功后，控制台会显示：
Running on local URL: http://127.0.0.1:7860 ... CUDA available, using prompt: ...- 若控制台再无 “Torch is not able to use GPU” 报错，则说明 GPU 已正常工作，可以在浏览器中打开
http://127.0.0.1:7860进行图像生成测试。
七、常见 Q\&A
Q：我在 Windows 上也出现同样错误，怎么排查？
- A：首先打开 “NVIDIA 控制面板” → “系统信息” 检查驱动版本是否与 NVIDIA 官网一致。
然后打开命令行（Win+R，输入 cmd），执行：
nvidia-smi确认驱动正常。
接着在 Python 中执行：
import torch print(torch.cuda.is_available())若输出
False，请检查以下：- 是否安装了支持对应 CUDA 版本的 PyTorch（二进制包需与本机 CUDA 版本一致）。
- 是否安装了最新的 Visual C++ Redistributable（某些情况下缺少依赖也会导致
torch.cuda加载失败）。 - 如果使用 Anaconda，请在 Anaconda Prompt 中执行上述命令，避免与系统默认 Python 环境冲突。
Q：我只有 AMD 显卡（ROCm 生态），能让 WebUI 使用 GPU 吗？
- A：目前主要依赖 NVIDIA CUDA，官方 PyTorch ROCm 支持尚不完善。部分社区 fork 提供了 ROCm 版本，可尝试安装
pip install torch==<roc版本>，但稳定性较差。建议使用 CPU 或切换到 NVIDIA 硬件。
- A：目前主要依赖 NVIDIA CUDA，官方 PyTorch ROCm 支持尚不完善。部分社区 fork 提供了 ROCm 版本，可尝试安装
Q：使用 Docker 部署 WebUI，可否避免 “Torch is not able to use GPU”？
A：使用 Docker 时，需要确保：
- 主机已安装 NVIDIA 驱动且版本符合要求。
- 安装
nvidia-container-toolkit并在运行容器时加上--gpus all。 - Dockerfile 中使用带 CUDA 支持的 PyTorch 基础镜像（如
pytorch/pytorch:2.1.0-cuda11.7-cudnn8-runtime）。
示例运行命令：
docker run --gpus all -v /home/user/sd-webui:/workspace/sd-webui -it sd-webui-image:latest- 若镜像中 PyTorch 与宿主机 CUDA 版本不匹配，也会出现相同错误，需要自行调试镜像中 CUDA 与 PyTorch 二进制的兼容性。
八、小结
本文针对 RuntimeError: Torch is not able to use GPU 错误，从以下几方面进行了详细解析：
- 问题含义：当 PyTorch 无法检测到 CUDA 时即会抛出该错误，导致 Stable Diffusion WebUI 只能在 CPU 上运行。
- 系统环境检查：通过
nvidia-smi、nvcc --version验证 NVIDIA 驱动及 CUDA Toolkit 是否安装与配置正确。 - PyTorch GPU 支持：在 Python 中运行简单脚本，检查
torch.cuda.is_available()，并根据需要重新安装与系统 CUDA 兼容的 GPU 版本 PyTorch。 - WebUI 安装与调试：以 AUTOMATIC1111 WebUI 为例，说明如何在虚拟环境中跳过脚本自动安装（防止安装到 CPU 版），并保证最后启动时 PyTorch 能够正常调用 GPU。
- 综合排查流程图：通过 Mermaid 流程图，归纳了从驱动到 CUDA、从 PyTorch 到 WebUI 的逐步查验步骤。
- 案例实战：在 Ubuntu22.04 + RTX3070 + CUDA11.7 平台下，从零搭建环境并成功启动 Stable Diffusion WebUI 的完整过程。
- 常见问答：解答了 Windows、AMD GPU、Docker 等多种场景下的常见疑问。
在实际项目中，遇到 “Torch is not able to use GPU” 错误时，应按从系统层（驱动）→ CUDA 层 → PyTorch 层 → WebUI 层 的顺序逐步排查。通过本文提供的代码示例、命令行示例和流程图，你可以快速定位问题根源并加以解决，让 Stable Diffusion WebUI 正常使用 GPU 进行加速推理。
