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

进入ComfyUI的Python运行目录：

示例路径（Windows 嵌入式发行版）：
D:\ComfyUI\_windows\python\_embeded

打开终端工具（CMD / PowerShell / Terminal），切换到上述路径，执行以下命令安装核心依赖：

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

等待所有包自动下载并完成安装。这个过程可能因网络状况持续数分钟。

---

如果你使用的是 Git克隆版本 或将项目放在自定义路径中，请根据实际情况调整命令中的路径部分。

例如：

C:\Users\YourName\ComfyUI\python\python.exe -m pip install -r C:\Users\YourName\ComfyUI\requirements.txt

更推荐先进入项目根目录，再相对调用解释器和依赖文件：

cd C:\Users\YourName\ComfyUI
..\python\python.exe -m pip install -r requirements.txt

这样可以避免长路径输入错误，也便于后续脚本复用。

---

对于已有全局 Python 环境（建议 ≥3.10）的用户，推荐通过虚拟环境隔离依赖，防止与其他AI项目冲突。

创建独立环境：

python -m venv comfyui_env

激活环境（Windows）：

comfyui_env\Scripts\activate

然后安装依赖：

pip install -r D:\ComfyUI\ComfyUI\requirements.txt

注意：确保 requirements.txt 文件存在且路径无误。若在激活后仍报错找不到模块，检查是否在正确的环境中执行命令。

---

网络较慢或频繁超时？立即切换为国内镜像源可显著提升成功率。

添加 -i 参数指定镜像地址：

pip install -r D:\ComfyUI\_windows\ComfyUI\requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

常用镜像列表：
- 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
- 阿里云：https://mirrors.aliyun.com/pypi/simple/
- 豆瓣：https://pypi.douban.com/simple/

强烈建议在网络受限环境下始终使用镜像源，尤其是安装 torch 这类大型包时。

进一步优化安装体验，可加入超时与重试控制：

pip install -r requirements.txt \
  --index-url https://pypi.tuna.tsinghua.edu.cn/simple \
  --timeout 100 \
  --retries 3 \
  --prefer-binary

其中 --prefer-binary 优先使用预编译二进制包，减少本地编译失败风险。

---

如果提示 WARNING: You are using pip version X.X.X; however, version Y.Y.Y is available，先升级 pip 再继续：

python -m pip install --upgrade pip

老版本 pip 在处理复杂依赖时容易出错，保持更新是稳定性的基本保障。

---

某些插件节点需要额外依赖，主依赖安装完成后按需追加即可。

例如启用 xformers 加速推理：

python -m pip install xformers

但注意：Windows 下直接 pip install xformers 经常失败——因其需从源码构建，对编译环境要求高。

推荐方案：使用社区维护的预编译 wheel 包。

前往 https://github.com/C43H66N12O12S2/xformers-wheels
查找匹配你当前 Python 版本（如 cp310）和 CUDA 版本（如 cu118）的 .whl 文件

下载后本地安装：

python -m pip install xformers-0.0.20+cbfc91d.d20231129-cp310-cp310-win_amd64.whl

或尝试官方支持渠道的测试版本：

pip install --pre xformers --index-url https://pypi.org/simple/ --extra-index-url https://download.pytorch.org/whl/cu118

务必保证 PyTorch 与 CUDA 版本一致，否则运行时会抛出兼容性错误。

---

验证环境是否就绪：启动主程序观察输出。

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

若终端无红色异常堆栈，并在浏览器中成功加载 http://127.0.0.1:8188 的节点编辑界面，则表明环境配置成功。

首次启动可能会自动下载模型缓存或初始化组件，稍等片刻即可。

---

理解 ComfyUI 的运行依赖结构

ComfyUI 并非普通Web应用，它是一个基于节点图的 AI 工作流引擎，将 Stable Diffusion 的每个环节拆解为可编程模块——CLIP 编码、UNet 推理、VAE 解码、采样调度等全部以节点形式呈现。

这种设计带来了极强的灵活性，但也对底层环境提出了严苛要求。任何一个关键依赖缺失，都可能导致特定节点无法加载或流程中断。

必须完整安装 requirements.txt 中列出的核心组件：

包名	作用说明
torch, torchvision	深度学习计算核心，支持 GPU 加速
numpy, Pillow	图像数据处理与张量操作基础
flask, websockets	提供前后端通信服务
onnxruntime	支持 ONNX 格式模型推理（如 ControlNet-TensorRT）
transformers	HuggingFace 模型加载能力支撑

特别提醒：不要手动删减 requirements.txt 中的内容，即使某些包看似“未被直接引用”。很多插件在运行时动态导入，静态分析无法检测其依赖关系。

---

常见问题及应对策略

❌ 报错：ModuleNotFoundError: No module named 'xxx'

最常见于多Python环境共存场景。

排查步骤：
1. 确认当前使用的 python 是否是你想安装依赖的那个解释器；
2. 使用绝对路径调用 pip 安装：
cmd D:\ComfyUI\_windows\python\_embeded\python.exe -m pip install xxx
3. 避免混用系统级 pip（如通过 py -m pip 或全局 pip install）。

可通过以下命令查看当前解释器位置：

where python

确保其指向 ComfyUI 自带或你明确指定的 Python 目录。

---

⏳ 安装缓慢或频繁中断

根本原因通常是连接 PyPI 官方源不稳定。

解决方案已多次强调：换镜像！

完整命令示例：

pip install -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn \
  --timeout 100 \
  --retries 3

--trusted-host 可避免 SSL 验证问题，尤其在企业代理网络下有效。

---

💥 xformers 安装失败（Windows 典型痛点）

除了前面提到的预编译包方案，还可考虑替代路径：

方案一：跳过安装（接受性能损失）

xformers 不是强制依赖，不装也能跑，只是推理速度慢、显存占用更高。

方案二：改用 flash-attn + 官方 PyTorch 优化

部分新版 PyTorch 已集成类似优化，配合如下参数启动可获得接近效果：

--use-pytorch-cross-attention

具体取决于 ComfyUI 版本和插件支持情况。

方案三：使用 WSL2 环境安装

Linux 下 xformers 编译成功率远高于 Windows，适合愿意折腾的高级用户。

---

多项目环境管理建议（进阶实践）

如果你同时运行 WebUI、Fooocus、InvokeAI 等多个 AI 工具，强烈建议为 ComfyUI 单独建立专属环境。

不同项目的 torch 版本、CUDA 支持方式差异极大，混用极易引发冲突。

推荐三种管理方式：

1. 使用 conda（推荐给科研/开发用户）

conda create -n comfyui python=3.10
conda activate comfyui
pip install -r D:\ComfyUI\ComfyUI\requirements.txt

conda 能精确控制 Python 版本和原生库依赖，适合长期维护多个实验环境。

2. 使用 venv + 手动激活（轻量级选择）

python -m venv comfyui_env
comfyui_env\Scripts\activate

简单直接，无需额外安装包管理器。

3. 使用 poetry（适合开发自定义节点）

# pyproject.toml 示例
[tool.poetry]
name = "comfyui-dev"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.10"
torch = { url = "https://download.pytorch.org/whl/cu118/torch-2.1.0%2Bcu118-cp310-cp310-win_amd64.whl" }
comfy-cli = "*"

poetry 提供了更好的依赖锁定机制，适用于团队协作或发布插件。

---

正确配置 Python 环境是运行 ComfyUI 的第一道门槛，也是最关键的一步。无论是嵌入式发行版自带的 Python，还是自建虚拟环境，只要路径清晰、命令准确、网络通畅，绝大多数安装问题都能迎刃而解。

当你看到浏览器中流畅展开的节点编辑器界面时，就意味着你已经站在了强大工作流系统的入口。接下来，只需导入模型、加载 ControlNet、连接 LoRA 节点，就能构建出高度定制化的生成流水线。

真正的生产力，从此刻开始释放。