ComfyUI依赖包安装失败原因

先判断你装的是哪一层依赖

ComfyUI 的依赖分成三层，报错处理方式完全不同，先定位层级能省掉一半时间：

1. 主程序依赖：ComfyUI 仓库根目录 requirements.txt 里的包，以及 PyTorch 本体。
2. 自定义节点依赖：custom_nodes/<节点名>/requirements.txt。这是最常见的失败来源——主程序能启动，但某个节点红框报 import 失败。
3. 系统级依赖：编译某些包需要的 C/C++ 构建工具、Git、以及显卡驱动。

失败原因分类与对应处理

1. 装到了错误的 Python 解释器（便携版最高频）

如果你用的是 Windows 便携包，ComfyUI 使用的是包内自带的嵌入式 Python，而不是系统 Python。此时在 CMD 里直接敲 pip install xxx 会装进系统 Python，ComfyUI 完全看不到。

正确做法是显式指定包内解释器：

python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\某节点\requirements.txt

如果你用的是自己建的虚拟环境，则必须先激活该环境再安装，或同样用 <venv>/bin/python -m pip 的显式写法。判断依据：启动 ComfyUI 时控制台打印的 Python 路径，就是你该用的解释器。

2. 缺少 C/C++ 编译工具链

报错里出现 error: Microsoft Visual C++ 14.0 or greater is required、building wheel for xxx failed、fatal error: Python.h: No such file or directory 这类信息，说明这个包没有预编译好的 wheel，需要在本机编译。

• Windows：安装 Visual Studio Build Tools 并勾选 C++ 桌面开发组件，装完重开终端。
• Linux：安装发行版对应的编译工具与 Python 开发头文件（如 build-essential 与 python3-dev 系列包）。
• 可行的替代思路：优先找该包的预编译 wheel，或降到有 wheel 的相邻版本，避免本机编译。

3. torch 与 CUDA / 显卡驱动不匹配

特征是安装本身"成功"，但运行时报 Torch not compiled with CUDA enabled，或者 ComfyUI 启动后只识别到 CPU。这类问题的根因是 PyTorch 的构建变体（CPU 版 / 不同 CUDA 版本）与你机器上的驱动不对应。

处理顺序：先确认显卡驱动可用，再到 PyTorch 官方安装页按你的平台和 CUDA 组合生成安装命令，然后卸载现有 torch 系列包重新安装。切忌用一条网上抄来的固定命令，因为对应关系随版本变化，官方安装页才是唯一可靠来源。

4. 网络与 pip 源问题

报错含 ReadTimeoutError、Connection reset、Could not find a version that satisfies the requirement 时，先怀疑网络。可切换到可用的国内镜像源，或为 pip 配置代理。注意：换源只解决"下不下来"，不解决"包不兼容"。

5. 路径含中文、空格或过深

部分包的编译脚本和缓存路径处理不健壮，安装目录里有中文、空格，或路径超长时会出现莫名失败。把 ComfyUI 放在纯英文短路径下（例如盘根目录下的英文目录）是成本最低的规避方式。

6. 权限不足

报 Permission denied 或 Access is denied 时，常见原因是杀毒软件锁定文件、或目标目录需要管理员权限。可尝试关闭实时防护后重试，或把 ComfyUI 移到当前用户可写的目录。

7. 依赖互相冲突

多个自定义节点各自钉不同版本的同一个包（典型如 numpy、transformers、opencv 系列），后装的会顶掉前装的，导致某个节点转而报错。判断方法是看是否"装好 A 节点后 B 节点坏了"。稳妥做法是为不同工作流准备独立环境，或减少同时安装的重型节点数量。

推荐排查顺序（按性价比）

1. 确认解释器：启动日志里的 Python 路径，是否就是你 pip 用的那个。
2. 把完整报错的最后 20 行读完，抓关键字（编译 / 网络 / 版本 / 权限）。
3. 单独重装报错的那一个包，而不是整份 requirements，缩小范围。
4. 如为自定义节点，先禁用该节点确认主程序能正常启动，再单独修它。
5. 仍不行时，去该自定义节点的 GitHub Issues 搜报错关键字，作者通常已给出说明。

使用场景

• 刚解压便携包，装完某个节点后启动报红框。
• 更新 ComfyUI 或更新节点后，原本正常的工作流突然缺依赖。
• 换新机器/换显卡后 torch 相关能力失效。
• 公司内网环境下 pip 无法直连外网。

本页信息来源

本页基于 ComfyUI 官方仓库与官方文档中的安装说明、以及 pip / PyTorch 官方安装指引的通用规则整理。文中不列具体版本号与依赖版本对应表，因为该对应关系随上游发布持续变化，请以 PyTorch 官方安装页与各自定义节点仓库的 README 为准。