如何修复 ComfyUI 自定义节点 requirements.txt 未安装的问题
修复因 requirements.txt 依赖项未安装到正确 Python 环境而导致加载失败的 ComfyUI 自定义节点。
社区知识
本页内容基于常见的 ComfyUI 故障排查模式，尚未在所有环境中经过完整测试。在更改软件包之前，请备份您的环境。
如果 ComfyUI 自定义节点在启动日志中显示 IMPORT FAILED，原因是 ModuleNotFoundError，最常见的原因是该节点的 requirements.txt 从未被安装过。
将自定义节点克隆或下载到 custom_nodes/ 目录中只是复制了代码。该代码所依赖的 Python 包必须单独安装。
自定义节点依赖问题通常不是单个随机软件包问题，而是一条修复链：节点缺失、克隆尝试、安装 requirements、重启后出现新的 ModuleNotFoundError。请按这条链路排查。
快速解答
适用于 GitHub Windows 便携包：
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build安装前请务必先阅读 requirements 文件，检查是否存在有风险的包变更。
错误的表现形式
IMPORT FAILED: ComfyUI-ExampleNode
Traceback (most recent call last):
File "...\custom_nodes\ComfyUI-ExampleNode\__init__.py", line 4, in <module>
import somepackage
ModuleNotFoundError: No module named 'somepackage'节点文件夹存在于 custom_nodes/ 中，但导入失败，因为 somepackage 未被安装。
真实修复案例中常见的依赖模式
以下模块在自定义节点故障中很常见。重新克隆同一节点之前，建议先逐一排查：
| 缺失模块 | 常见工作流场景 | 首要验证事项 |
|---|---|---|
triton | 加速、SageAttention、视频、大模型工作流 | 安装前先确认该依赖是可选的还是必需的 |
sageattention | Wan/视频加速及强制 attention 标志 | 除非工作流确实需要，否则移除强制标志 |
onnx / onnxruntime | 人脸、姿态、DWPose、ReActor、IPAdapter、视频辅助工具 | 优先使用 CPU 版 onnxruntime，除非确实需要 GPU ONNX |
llama_cpp | GGUF 提示辅助工具、本地 LLM/VLM 节点 | 包名通常是 llama-cpp-python，而非 llama_cpp |
nunchaku | 基于 Nunchaku 的 FLUX/Qwen/SANA 工作流 | 不要安装 PyPI 上无关的 nunchaku 包 |
sox / decord | 音频和视频辅助节点 | 先确认节点包来源，不要批量安装所有视频相关包 |
groundingdino / segment_anything | 目标检测、定位、分割、遮罩 | 参考 SAM/GroundingDINO 导入指南，并确认模型资源 |
dlib / nvvfx | 人脸/视频特效工作流 | 原生 wheel 包和平台支持至关重要，请先阅读插件 README |
如果某个模块不在表格中，同样适用相同规则：先找到导致失败的插件，再将所需的最小依赖安装到启动 ComfyUI 的 Python 环境中。
原因分析
- 手动 git clone 但未执行 pip install：您克隆了节点仓库，但忘记安装其依赖项
- ComfyUI Manager 部分安装：Manager 可能克隆了仓库，但依赖安装步骤静默失败
- 环境被重建：您重新安装了 ComfyUI 或更新了便携包，导致之前安装的包被清除
- 安装时使用了错误的 Python：依赖被安装到了系统 Python，而非 ComfyUI 的嵌入式 Python
- 没有 requirements.txt：部分节点只在 README 中列出依赖项，而未提供 requirements 文件
分步修复方法
第一步：找到失败的节点
检查 ComfyUI 启动日志中的 IMPORT FAILED 行。该行会告诉您哪个自定义节点文件夹失败，以及缺少哪个模块。
第二步：检查 requirements.txt 是否存在
dir ComfyUI\custom_nodes\<node-name>\requirements.txt如果文件存在，继续第三步。如果不存在，请在 GitHub 上查看该节点的 README，了解手动安装依赖的说明。
第三步：安装前先阅读 requirements 文件
type ComfyUI\custom_nodes\<node-name>\requirements.txt注意以下风险信号：
| 需要注意的内容 | 风险 |
|---|---|
torch、torchvision、torchaudio | 可能将您启用 CUDA 的 PyTorch 替换为 CPU 版本 |
未锁定版本（无 == 或 >=） | 可能安装不兼容的版本 |
已有 opencv-python-headless 时出现 opencv-python | 可能导致 DLL 冲突 |
| 版本锁定过旧或过新 | 可能与其他节点冲突 |
如果文件看起来安全，可以继续。如果文件中包含 torch 或其他核心包，请考虑仅手动安装实际缺失的包，而不是全部安装。
第四步：安装依赖项
适用于 Windows 便携版：
.\python_embeded\python.exe -s -m pip install -r ComfyUI\custom_nodes\<node-name>\requirements.txt适用于手动创建的 venv：
python -m pip install -r custom_nodes/<node-name>/requirements.txt第五步：如果 requirements 文件会破坏您的环境
与其安装所有内容，不如只安装具体缺失的包：
.\python_embeded\python.exe -s -m pip install somepackage当 requirements 文件包含 torch 等核心包时，这种方式更为安全。
第六步：验证
重启 ComfyUI，确认 IMPORT FAILED 行已消失：
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build批量安装所有自定义节点的依赖项
如果多个节点存在缺失的依赖项，可以批量安装，但这带来更高的风险：
for /d %d in (ComfyUI\custom_nodes\*) do if exist "%d\requirements.txt" .\python_embeded\python.exe -s -m pip install -r "%d\requirements.txt"警告：盲目运行此命令可能导致依赖冲突。更安全的做法是逐个节点安装依赖，每次安装后检查是否有错误。
不应盲目运行 pip install 的情况
- 运行前始终先阅读
requirements.txt——部分节点作者会锁定强制性的 torch 版本 - 如果安装后
pip check显示冲突，不要继续安装更多依赖，先解决冲突 - 如果 requirements 文件非常陈旧，锁定的版本可能无法与您当前的 Python 或 PyTorch 兼容
- 如果只需要某个包本身而非其依赖树，可考虑对单个包使用
--no-deps
Wonderful Launcher 如何提供帮助
Wonderful Launcher 可以帮助检测具有未安装依赖项的自定义节点，并协助安全安装这些依赖。它会在安装前检查冲突，并帮助防止 requirements 破坏您的核心 PyTorch 环境。
下载 Wonderful Launcher——免费使用，帮助管理自定义节点依赖项。
相关错误
参考来源
先按上面的步驟定位根因。还卡住时，可以下载 Wonderful Launcher 检查目前机器；启动器原生修复、任务日誌和執行階段检查会集中在一起。credits 只用於图片生成和按量工具。
下载 Wonderful Launcher查看 credits 方案这篇文件解決了你的問题嗎？
你的回饋会帮助我们優先補強真實 ComfyUI 排障文件。