ComfyUI依赖安装指南：快速配置Python环境

你刚下载完 ComfyUI 的源码，双击 main.py 却弹出一连串“ModuleNotFoundError”？别急——这不是软件的问题，而是 Python 环境还没准备好。

ComfyUI 不是普通应用，它是一个节点式 AI 工作流引擎，运行时需要精确匹配的依赖库版本。直接执行只会失败，必须先正确安装依赖。本文不讲理论，只给最稳、最快的操作路径，覆盖 Windows 内建环境、Conda 管理、Linux/macOS 部署三大场景，帮你绕开所有常见坑点。

---

进入 Python 执行目录：从哪里开始？

打开你的 ComfyUI 文件夹，结构应该长这样：

ComfyUI/
├── main.py
├── requirements.txt
├── nodes/
├── web/
└── python/                  ← 只有打包版才有

关键在于：用哪个 Python 解释器？

如果你使用的是 _windows 发行包（比如从官网下载的 zip 包），里面自带了一个 python 目录，通常是：

D:\ComfyUI\_windows\python\_embeded

这就是我们要用的解释器位置。右键点击该文件夹空白处，选择「在此处打开终端」或「打开命令窗口」。

输入以下命令测试是否能调用 Python：

D:\ComfyUI\_windows\python\_embeded>python --version

如果返回 Python 3.10.x，说明环境可用。若提示“不是内部或外部命令”，请改用完整路径调用：

D:\ComfyUI\_windows\python\_embeded\python.exe --version

记住这个可执行文件的位置，后续所有操作都要显式调用它，避免系统默认 Python 干扰。

---

安装依赖：一行命令搞定核心库

现在切换到 requirements.txt 所在的主目录（通常是 ComfyUI 根目录），然后执行安装命令。

假设你的项目根目录在：

D:\ComfyUI\_windows\ComfyUI

而 Python 解释器在：

D:\ComfyUI\_windows\python\_embeded\python.exe

那么完整命令为：

D:\ComfyUI\_windows\python\_embeded\python.exe -m pip install -r D:\ComfyUI\_windows\ComfyUI\requirements.txt

拆解一下：
- -m pip：以模块方式运行 pip，更稳定，避免 PATH 冲突
- -r xxx\requirements.txt：读取依赖清单批量安装
- 显式指定 python.exe 路径：确保使用嵌入式环境，不污染全局

正常输出会看到类似内容：

Collecting torch==2.0.1+cu118
  Downloading https://download.pytorch.org/whl/cu118/torch-2.0.1%2Bcu118-cp310-cp310-win_amd64.whl (2.5 GB)
...
Installing collected packages: torch, torchvision, numpy, pillow, flask...
Successfully installed torch-2.0.1+cu118 torchvision-0.15.2 ...

整个过程耗时 5–15 分钟，取决于网络速度和硬件性能。期间不要中断，尤其是 PyTorch 下载中。

💡 小技巧：国内用户建议加镜像源加速。例如临时使用清华 TUNA：

bash python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

---

更推荐的做法：用 Conda 创建独立环境

虽然内建 Python 方便，但长期使用建议迁移到 Conda 环境。好处很明显：
- 版本隔离，避免与其他项目冲突
- 更容易调试、扩展插件（如 ControlNet、IP-Adapter）
- 支持 CUDA 自动检测与优化安装

第一步：创建专用环境

确保已安装 Miniconda 或 Anaconda，然后运行：

conda create -n comfyui python=3.10
conda activate comfyui

激活后终端前缀会变成 (comfyui)，表示当前处于该环境中。

第二步：安装 PyTorch（按 GPU 情况选）

去 pytorch.org 查看最新命令。常见情况如下：

有 NVIDIA 显卡（CUDA 11.8）：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

无 GPU（纯 CPU 运行）：

pip install torch torchvision torchaudio

注意：这里不用 -r requirements.txt 先装全部依赖，因为 requirements.txt 中的 torch 包可能与你手动安装的冲突。建议先单独处理 PyTorch。

第三步：安装其余依赖

进入 ComfyUI 根目录：

cd D:\ComfyUI

然后安装剩余依赖（跳过 torch）：

pip install -r requirements.txt --no-deps
pip install -e .

或者你可以编辑 requirements.txt，注释掉 torch 行再整体安装。

这样做的结果是：PyTorch 来自官方渠道并启用 CUDA 支持，其他库由项目定义，两者互不干扰。

---

Linux / macOS 用户怎么装？

类 Unix 系统通常自带完善的开发工具链，流程反而更简洁。

1. 克隆仓库并进入目录

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

2. 建议使用虚拟环境隔离

python3 -m venv venv
source venv/bin/activate

激活后即可使用 pip 安装。

3. 升级 pip 并安装依赖

pip install --upgrade pip
pip install -r requirements.txt

⚠️ 注意：某些 Linux 发行版需要提前安装系统依赖，否则编译失败。

Ubuntu/Debian 示例：

bash sudo apt update sudo apt install python3-dev python3-venv ffmpeg libgl1 libglib2.0-0

这些包用于支持图像处理、GPU 加速等底层功能。

macOS 用户若遇到权限问题，请确认已安装 Xcode Command Line Tools：

xcode-select --install

---

常见错误及应对策略

❌ 找不到 torch 包？升级 pip！

典型报错：

Could not find a version that satisfies the requirement torch==2.0.1+cu118

原因很简单：旧版 pip 不识别带 +cu118 后缀的 wheel 文件。

解决办法：

python -m pip install --upgrade pip

然后再重试安装命令。这是几乎所有“找不到包”问题的第一解决方案。

---

❌ xformers 装不上怎么办？

xformers 是一个内存优化库，但在 Windows 上没有通用预编译包。

尝试指定索引源安装：

pip install -U xformers --index-url https://download.pytorch.org/whl/cu118

如果仍失败，可以直接从 requirements.txt 中注释掉这一行：

# xformers>=0.0.20

不影响主体功能运行，只是推理时显存占用略高一点。

---

❌ Permission Denied？别用 sudo！

尤其在 Linux/macOS 上，有人习惯性加 sudo pip install，这会导致权限混乱和后续无法更新。

正确做法永远是：使用虚拟环境或嵌入式 Python。

如果已经误操作导致权限异常，清理方法如下：

sudo chown -R $(whoami) ~/.local/lib/python*

然后重新创建干净的 venv 或 conda 环境。

---

❌ 模块找不到，比如 ‘folder_paths’？

报错示例：

ModuleNotFoundError: No module named 'folder_paths'

这不是缺包，而是启动方式错了。

❌ 错误示范：

D:\ComfyUI\_windows\python\_embeded>python D:\ComfyUI\_windows\ComfyUI\main.py

此时 Python 当前工作目录不在项目根路径，导入机制失效。

✅ 正确做法：

先进入项目根目录，再调用解释器：

cd D:\ComfyUI\_windows\ComfyUI
D:\ComfyUI\_windows\python\_embeded\python.exe main.py

这样才能让 Python 正确识别本地模块路径。

---

验证安装：看到这句话才算成功

运行主程序：

python main.py

等待几秒，看到如下输出即表示环境就绪：

Starting server
NODE_CLASS_MAPPINGS = ...
Registered node: KSampler
Registered node: LoadCheckpoint
Startup time: 4.5s
Go to http://127.0.0.1:8188 in your browser

打开浏览器访问 http://127.0.0.1:8188，出现图形界面，拖拽节点正常响应——恭喜，你的 ComfyUI 环境已完全就位。

---

最后几点实用建议

1. 优先使用虚拟环境
   无论是 venv 还是 conda，都比全局安装安全得多。多花一分钟设置，能省下几小时排错时间。

2. 保留原始 requirements.txt 备份
   插件安装可能会修改依赖列表，建议复制一份原始文件留作恢复用。

3. 定期更新依赖（谨慎操作）
   可通过 pip list --outdated 查看可更新项，但不要盲目升级 torch 或 diffusers，可能导致兼容性断裂。

4. 善用镜像源提升体验
   国内用户可永久配置 pip 源：

bash pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

常用镜像还包括阿里云、豆瓣等。

---

当依赖全部齐备，你就真正站在了节点式 AI 工程化的起点。不再依赖固定 UI，而是通过自由连接节点，构建属于自己的生成逻辑——加载模型、控制采样、接入 ControlNet、输出视频序列……一切皆可编程。

这才是 ComfyUI 的终极魅力所在。