ComfyUI ModuleNotFoundError: No module named 'sageattention' 修复
判断 ComfyUI No module named 'sageattention' 是可忽略的启动 warning，还是 Wan、HunyuanVideo、LTX、Qwen Image 工作流失败；优先切回 SDPA/Comfy，再安全检查 Python、Triton 和 SageAttention。
如果 ComfyUI 显示：
ModuleNotFoundError: No module named 'sageattention'先不要重装 ComfyUI，也不要马上运行 pip install sageattention。
这个错误可能只是启动日志里的一条可选加速警告，也可能是 WanVideoWrapper、HunyuanVideo、LTX、Qwen Image 或数字人工作流真的在调用 SageAttention。
两种情况的处理方式完全不同。
30 秒判断：你应该走哪条路线？
| 你看到的情况 | 是否致命 | 先做什么 |
|---|---|---|
| 启动日志出现 SageAttention warning，但 ComfyUI 能打开、能生成 | 通常不致命 | 不用安装，继续使用 |
| 运行工作流时报错并停止 | 致命 | 把节点后端从 sageattn 改为 sdpa、comfy、torch 或 auto |
启动命令中有 --use-sage-attention | 可能导致启动失败 | 删除该启动参数并重启 |
错误变成 No module named 'triton'、triton_key 或 tcc.exe | 卡在 Triton 层 | 先修复 Triton，再回来处理 SageAttention |
出现 DLL load failed while importing _fused | 已安装但二进制不兼容 | 不要反复重装，改回 SDPA 或寻找完全匹配的 wheel |
大多数用户不需要安装 SageAttention。
最快、风险最低的修复方式通常是：关闭 SageAttention，先让工作流用 PyTorch/SDPA 正常运行。
第 1 步：判断它是启动警告还是工作流错误
可以暂时忽略的启动警告
例如：
[WARNING] Warning: Could not load sageattention: No module named 'sageattention'
[WARNING] sageattention package is not installed, sageattention will not be available如果日志后面仍然出现：
To see the GUI go to: http://127.0.0.1:8188打开 ComfyUI，运行一个简单工作流。
只要满足下面三项，就不需要为了这条 warning 安装 SageAttention：
- ComfyUI 能打开；
- 工作流能够 queue；
- 图片或视频能够正常生成。
日志里继续出现 SageAttention warning，并不代表 ComfyUI 已损坏。
这条路线什么时候算完成？
ComfyUI 能启动、能 queue、能生成，就已经完成。不要为了让日志看起来更干净而安装可选 CUDA 加速包。
需要处理的运行时错误
例如：
ModuleNotFoundError: No module named 'sageattention'
Can't import SageAttention: No module named 'sageattention'
WanVideoWrapper sageattention error: No module named 'sageattention'如果错误出现在运行工作流时，并且任务直接停止，说明某个节点或启动参数真的要求使用 SageAttention。
继续执行第 2 步。
不一定致命的自动回退提示
例如：
unsupported head_dim: 256, using pytorch attention instead这句话通常表示 SageAttention 不支持当前 attention head dimension，程序正在尝试回退到 PyTorch attention。
先观察后面的日志：
- 工作流仍然继续生成：可以忽略；
- 后面出现完整 traceback，工作流停止：把节点后端改回 SDPA、PyTorch 或 Comfy。
不要只看到 unsupported head_dim 就开始重装依赖。
第 2 步：先关闭 SageAttention
这是风险最低，也最可能立即解决问题的一步。
方法 A：删除 --use-sage-attention
检查启动 ComfyUI 的 .bat 文件、快捷方式或启动命令。
如果里面有：
--use-sage-attention将这个参数删除，然后重新启动 ComfyUI。
这个参数会强制 ComfyUI 尝试加载 SageAttention。只有 Python、PyTorch、CUDA、GPU、Triton 和 SageAttention 构建版本全部兼容时，它才适合启用。
方法 B：修改工作流节点的 attention 后端
如果错误来自 WanVideoWrapper、HunyuanVideo、LTX、Qwen Image 或其他视频节点，打开报错节点。
优先检查模型加载节点、视频模型 loader 或 wrapper 节点中的这些字段：
attentionattention_backendattention_modeattn_modebackenduse_sageattentionsageattention
如果当前值是：
sage
sageattn
sageattention
SageAttention改成该节点下拉框中实际存在的非 SageAttention 选项，例如：
sdpa
comfy
torch
pytorch
auto
disabled
none不同节点提供的名称可能不同。不要手动填写不存在的值，直接选择下拉框中已有的非 SageAttention 后端。
保存工作流，然后重新 queue。
这条路线什么时候算修好？
工作流开始加载模型、进入采样或继续执行，并且不再因为 SageAttention 抛出致命 traceback，就算修复成功。
生成速度稍慢不代表工作流有问题，只表示它没有使用 SageAttention 加速。
只有在以下情况下，才需要继续安装：
- 节点没有其他 attention 后端；
- 工作流明确强依赖 SageAttention；
- 你已经有一个稳定环境，并且确实需要视频生成加速。
第 3 步：确认 ComfyUI 实际使用哪个 Python
最常见的失败原因不是“没有执行安装”，而是：
SageAttention 被安装到了系统 Python，但 ComfyUI 使用的是另一套 Python。
不要直接使用裸命令：
pip install sageattention先找到启动 ComfyUI 的解释器。
Windows ComfyUI Portable
在 ComfyUI_windows_portable 目录打开 PowerShell，执行：
.\python_embeded\python.exe -s -c "import sys; print(sys.executable)"
.\python_embeded\python.exe -s --version
.\python_embeded\python.exe -s -m pip show torch
.\python_embeded\python.exe -s -m pip show sageattention
.\python_embeded\python.exe -s -c "import torch; print('Torch:', torch.__version__); print('Torch CUDA:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available())"后续所有检查、安装和验证，都要继续使用：
.\python_embeded\python.exe不要前面使用 embedded Python，后面又改成系统的 python 或 pip。
手动安装或 venv
先激活用于运行 ComfyUI 的虚拟环境，然后执行：
python -c "import sys; print(sys.executable)"
python --version
python -m pip show torch
python -m pip show sageattention
python -c "import torch; print('Torch:', torch.__version__); print('Torch CUDA:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available())"如果最后显示：
CUDA available: False说明当前 PyTorch 没有正常使用 CUDA。
这种情况下应该先修复 PyTorch/CUDA，安装 SageAttention 不能解决问题。
使用 Wonderful Launcher 查找 Python 路径
如果你通过 Wonderful Launcher 管理 ComfyUI，通常可以在当前实例的启动日志开头找到启动命令或 Python 路径。搜索 python.exe、python_embeded 或启动命令；如果日志没有显示完整路径，就回到上面的命令，在实际 ComfyUI 目录里确认。
你需要确认的是：当前实例究竟由哪一个 Python executable 启动。找到这个路径后，后续所有 pip show、安装和验证命令都必须使用同一个 Python。
第 4 步：检查 Triton，但不要混淆包名和导入名
SageAttention 的 Windows 安装经常会卡在 Triton。
Windows 用户通常使用的发行包名称是：
triton-windows但 Python 中导入的模块名称仍然是：
import tritonWindows Portable 检查命令
.\python_embeded\python.exe -s -m pip show triton-windows
.\python_embeded\python.exe -s -c "import triton; print('Triton:', triton.__version__)"手动 venv 检查命令
python -m pip show triton-windows
python -c "import triton; print('Triton:', triton.__version__)"不要只执行：
pip show triton因为发行包可能叫 triton-windows，即使 import triton 已经可以正常工作，pip show triton 仍可能显示没有找到包。
如果出现以下错误：
No module named 'triton'
No module named 'triton_key'
tcc.exe not found请先使用：
完成 Triton 修复后，再回到本页验证 SageAttention。
第 5 步：决定是否真的值得安装 SageAttention
满足以下至少一个条件时，再考虑安装：
- 工作流或自定义节点明确要求 SageAttention；
- 节点没有 SDPA、PyTorch、Comfy 或 Auto 后端；
- 关闭 SageAttention 后工作流无法执行；
- 你在稳定环境中运行高分辨率或长视频任务；
- 你清楚当前 Python、PyTorch、CUDA 和 GPU 信息。
下面这些情况建议直接跳过：
- ComfyUI 能正常工作，只是启动 warning；
- 改成 SDPA 后工作流已经能生成；
- 当前还有其他插件或依赖错误；
- PyTorch 的
torch.cuda.is_available()是False； - 你不知道 ComfyUI 正在使用哪个 Python；
- 找不到与你当前环境完全匹配的 Windows wheel。
SageAttention 是可选加速组件，不是 ComfyUI 正常运行的基础依赖。
第 6 步：必须安装时，先记录环境并进入安装指南
Windows 上不存在一个适用于所有 ComfyUI 用户的万能 SageAttention 安装命令。
安装前至少记录以下信息：
GPU 和驱动
nvidia-smiPython 版本
Portable：
.\python_embeded\python.exe -s --versionvenv：
python --versionPyTorch 和 PyTorch CUDA 构建版本
Portable：
.\python_embeded\python.exe -s -c "import torch; print(torch.__version__); print(torch.version.cuda)"venv：
python -c "import torch; print(torch.__version__); print(torch.version.cuda)"Triton 版本
Portable：
.\python_embeded\python.exe -s -c "import triton; print(triton.__version__)"venv：
python -c "import triton; print(triton.__version__)"选择 wheel 时看 torch.version.cuda
选择 SageAttention wheel 时，以：
torch.version.cuda输出的 CUDA 版本为准。
不要直接使用 nvidia-smi 顶部显示的 CUDA Version 选择 wheel。nvidia-smi 显示的是显卡驱动能够支持的 CUDA 上限，不等于当前 PyTorch 使用的 CUDA 构建版本。
例如，一个 wheel 文件可能叫：
sageattention-2.2.0+cu128torch2.7.1-cp312-cp312-win_amd64.whl这个文件名通常同时限制：
cu128：对应 CUDA 12.8 构建；torch2.7.1：对应 PyTorch 2.7.1；cp312：对应 Python 3.12；win_amd64：对应 64 位 Windows。
它不是“Windows 用户都能安装”。
Python、PyTorch、PyTorch CUDA 构建或系统架构只要有一个不匹配，就可能从：
No module named 'sageattention'变成：
DLL load failed while importing _fused也可能出现黑图、崩溃或其他 CUDA 错误。
如果没有完全匹配的构建版本，优先回到 SDPA/Comfy，而不是在现有 ComfyUI 环境里盲目源码编译。
本文负责判断错误、恢复工作流并确认运行环境，不在这里维护一个适用于所有 Windows 环境的通用安装命令。
如果工作流确实必须使用 SageAttention，请继续查看：
在 Windows ComfyUI 中安装 SageAttention
安装完成后，返回本页执行第 7 步验证。
第 7 步：完成安装后，返回这里验证
完成安装后，不要只看终端是否显示 Successfully installed。
Windows Portable
.\python_embeded\python.exe -s -m pip show sageattention
.\python_embeded\python.exe -s -c "from sageattention import sageattn; print('SageAttention OK')"手动 venv
python -m pip show sageattention
python -c "from sageattention import sageattn; print('SageAttention OK')"两条命令都成功后，再重新启动 ComfyUI，运行原来的工作流。
真正的完成标准是：
pip show sageattention显示的安装位置属于 ComfyUI 使用的 Python；- 导入命令输出
SageAttention OK； - 原工作流开始采样或继续执行；
- 日志不再因为 SageAttention 出现致命 traceback。
如果导入时出现 Triton、DLL、CUDA 或编译器错误，不要继续重复安装 SageAttention。
根据新错误进入下面的分流。
修复失败后看这里
| 新错误或现象 | 常见原因 | 下一步 |
|---|---|---|
安装后仍然是 No module named 'sageattention' | 装到了错误的 Python | 使用 ComfyUI 实际使用的 Python 重新检查 |
No module named 'triton' | Triton 未安装或装错环境 | 先修复 triton-windows |
pip show triton 找不到，但 import triton 成功 | 查询了错误的发行包名 | Windows 使用 pip show triton-windows |
DLL load failed while importing _fused | wheel 与 Python、Torch、CUDA 或 GPU 架构不匹配 | 卸载不匹配版本，改回 SDPA 或寻找完全匹配的 wheel |
unsupported head_dim，但仍在生成 | 已自动回退 PyTorch attention | 可以继续使用，不需要安装 |
unsupported head_dim 后任务停止 | 当前 SageAttention 路径不兼容模型结构 | 把节点后端改回 SDPA、PyTorch 或 Comfy |
tcc.exe、编译器或 Triton 错误 | Triton Windows 环境不完整 | 先修 Triton，不要继续重装 SageAttention |
| 安装后原本正常的节点开始报错 | 新依赖破坏了现有环境 | 卸载 SageAttention/Triton 变更并回退 |
| 找不到完全匹配的 wheel | 当前版本组合没有现成构建 | 不要硬装，使用 SDPA/Comfy |
如何回退到安装前状态
如果安装 SageAttention 后 ComfyUI 出现更多错误，先停止继续升级其他包。
使用 ComfyUI 对应的 Python 卸载 SageAttention。
Windows Portable：
.\python_embeded\python.exe -s -m pip uninstall sageattention手动 venv：
python -m pip uninstall sageattention然后：
- 删除启动参数中的
--use-sage-attention； - 把工作流节点改回
sdpa、comfy、torch或auto； - 重启 ComfyUI；
- 用简单工作流确认基础环境能够正常生成。
不要在回退时顺手升级 PyTorch、CUDA 和全部自定义节点。一次只撤销一个变更，否则很难判断是哪一步造成问题。
为什么重装 ComfyUI 通常没有用
这个报错通常与 ComfyUI 主程序文件无关。
重装 ComfyUI 无法自动解决：
- 包安装到了错误的 Python；
- 工作流节点强制选择了 SageAttention；
- PyTorch 是 CPU-only；
- Triton 没有正常导入；
- wheel 与 Python、Torch 或 CUDA 不匹配；
DLL load failed；- 启动脚本保留了
--use-sage-attention； - 从其他电脑复制过来的环境依赖不兼容。
如果多个插件和 Python 包同时失败，请先查看：
SageAttention 是什么
SageAttention 是一个用于加速 Attention 计算的 CUDA 项目。
ComfyUI 可以通过以下两种入口调用它：
- 启动参数：
--use-sage-attention- 自定义节点或模型加载节点中的 attention 后端：
sage
sageattn
sageattention这两个入口相互独立。
即使启动命令没有 --use-sage-attention，某个 Wan、HunyuanVideo、LTX 或 Qwen Image 节点仍然可能主动导入 SageAttention。
反过来，即使电脑没有安装 SageAttention，只要工作流使用 SDPA、PyTorch 或 Comfy attention，大多数情况下仍然可以正常运行。
常见问题
为什么 WanVideoWrapper 会报 No module named 'sageattention'？
WanVideoWrapper 等视频节点通常允许选择 attention 后端。
如果模型加载节点选择了 sageattn 或 sageattention，但当前 Python 没有安装对应包，工作流就会停止。
先把节点改成下拉框中已有的：
sdpa
comfy
torch
pytorch
auto只有节点没有其他后端，或者你明确需要 SageAttention 加速时，才进入安装流程。
为什么 pip install sageattention 成功了，ComfyUI 仍然报错？
因为 pip 可能属于系统 Python、Conda 或另一个 venv。
ComfyUI Portable 通常使用：
ComfyUI_windows_portable\python_embeded\python.exe用哪一个 Python 启动 ComfyUI，就必须用同一个 Python 执行安装、pip show 和导入验证。
No module named 和 DLL load failed 有什么区别？
No module named 'sageattention'表示 Python 没找到这个包，常见原因是没安装或装错环境。
DLL load failed while importing _fused表示 Python 已经找到 SageAttention，但其 CUDA 二进制扩展无法加载。
后者通常是 Python、PyTorch、CUDA、Triton、GPU 架构或 wheel 不兼容，不是再运行一次 pip install 就能解决。
unsupported head_dim 一定是错误吗？
不一定。
如果后面写着：
using pytorch attention instead并且工作流继续生成，说明程序已经回退到 PyTorch attention。
只有工作流随后停止或出现完整 traceback 时，才需要把节点后端手动切回 SDPA、PyTorch 或 Comfy。
为什么 Windows 要检查 triton-windows，代码里却是 import triton？
因为发行包名称和 Python 导入模块名称可以不同。
Windows 下常见的是：
python -m pip show triton-windows但验证导入时使用：
python -c "import triton; print(triton.__version__)"ComfyUI Desktop 也能使用 python_embeded 命令吗？
不一定。
python_embeded 主要对应常见的 Windows Portable 目录结构。Desktop 或其他管理器可能使用自己的托管环境。
应先从启动日志、应用终端或运行时信息中找到实际 Python 路径，不要直接照搬 Portable 路径。
我必须安装 SageAttention 才能运行视频工作流吗？
通常不需要。
很多视频节点同时提供 SDPA、PyTorch、Comfy 或 Auto 后端。SageAttention 主要用于加速，不一定是模型运行的必要条件。
先用非 SageAttention 后端确认工作流可以正常执行，再决定是否值得增加依赖复杂度。
相关指南
来源参考
- SageAttention 官方 GitHub 仓库
- SageAttention PyPI 页面
- ComfyUI 命令行参数
- ComfyUI issue：SageAttention 安装到错误 Python 的案例
- WanVideoWrapper issue：模型加载时找不到 SageAttention
- ComfyUI issue：SageAttention DLL load failed
- triton-windows PyPI 页面
- Triton Windows 当前项目
- Triton Windows 历史仓库
- NVIDIA CUDA Toolkit、Driver 和 Architecture Matrix
先按上面的步驟定位根因。还卡住时，可以下载 Wonderful Launcher 检查目前机器；启动器原生修复、任务日誌和執行階段检查会集中在一起。credits 只用於图片生成和按量工具。
下载 Wonderful Launcher查看 credits 方案这篇文件解決了你的問题嗎？
你的回饋会帮助我们優先補強真實 ComfyUI 排障文件。
ModuleNotFoundError: No module named 'triton'（ComfyUI）
修复 ComfyUI 中的 ModuleNotFoundError: No module named 'triton'——区分无害的 comfy_kitchen 日志与阻塞性的 SageAttention、WanVideoWrapper 或加速栈故障。
ComfyUI ModuleNotFoundError: No module named 'insightface' 修复
修复 ComfyUI 中 ReActor、IPAdapter FaceID、InstantID、PuLID 及其他换脸或人脸分析节点在 Windows 上报告 No module named 'insightface' 的问题。