ComfyUI的强大功能让无数AI绘画爱好者心动,但在实际安装过程中,很多人却卡在了第一步。不同操作系统的环境差异、Python版本冲突、依赖包安装失败等问题层出不穷,让原本简单的安装变成了技术难题。
本文将提供一份完整的ComfyUI安装指南,涵盖Windows、Mac、Linux三大平台的详细步骤。从环境准备到成功运行,每个关键节点都有对应的解决方案。同时,我们还会提供测试脚本,帮你快速验证安装是否成功。
重点内容:系统环境要求、分步安装流程、常见错误速查表、以及备用的云端API方案。
ComfyUI 安装前的环境要求
在开始ComfyUI下载安装之前,我们需要确保系统满足基本运行条件:
🔧 硬件配置要求
配置项 | 最低要求 | 推荐配置 | 说明 |
---|---|---|---|
显卡 | 4GB VRAM | 8GB+ VRAM | 支持NVIDIA/AMD/Apple Silicon |
内存 | 8GB RAM | 16GB+ RAM | 大模型需要更多内存 |
存储 | 20GB 可用空间 | 50GB+ 可用空间 | 模型文件占用空间较大 |
CPU | 4核心 | 8核心以上 | CPU模式下影响生成速度 |
💻 软件环境要求
系统平台 | Python版本 | 其他依赖 | 特殊说明 |
---|---|---|---|
Windows 10/11 | Python 3.8-3.11 | Visual Studio Build Tools | 推荐使用Conda环境 |
macOS 10.15+ | Python 3.8-3.11 | Xcode Command Line Tools | Apple Silicon需特殊配置 |
Linux (Ubuntu/CentOS) | Python 3.8-3.11 | gcc, g++, cmake | 依赖包管理相对简单 |
⚠️ 重要提醒:Python 3.12目前可能存在兼容性问题,建议使用3.8-3.11版本。
ComfyUI 下载与获取方式
📥 官方下载渠道
方式一:GitHub Release 下载(推荐)
# 1. 访问官方GitHub仓库
https://github.com/comfyanonymous/ComfyUI
# 2. 下载最新Release版本
# Windows用户下载: ComfyUI_windows_portable_nvidia_cu121_or_cpu.7z
# 或者通过命令行下载
curl -L https://github.com/comfyanonymous/ComfyUI/archive/refs/heads/master.zip -o comfyui.zip
方式二:Git克隆(开发者推荐)
# 克隆ComfyUI源码
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
# 查看版本信息
git log --oneline -5
🔄 ComfyUI 版本选择策略
版本类型 | 适用场景 | 更新频率 | 稳定性 |
---|---|---|---|
Stable Release | 生产环境、新手用户 | 月度更新 | ⭐⭐⭐⭐⭐ |
Master Branch | 体验新功能 | 频繁更新 | ⭐⭐⭐⭐ |
Dev Branch | 开发测试 | 实时更新 | ⭐⭐⭐ |
Windows 平台 ComfyUI 安装教程
🪟 Windows 安装步骤详解
步骤1:Python环境准备
# 检查Python版本
python --version
# 如果没有Python,从官网下载安装
# https://www.python.org/downloads/
# 推荐使用Conda管理环境
conda create -n comfyui python=3.10
conda activate comfyui
步骤2:下载ComfyUI
# 下载并解压ComfyUI
Invoke-WebRequest -Uri "https://github.com/comfyanonymous/ComfyUI/archive/refs/heads/master.zip" -OutFile "comfyui.zip"
Expand-Archive -Path "comfyui.zip" -DestinationPath "."
cd ComfyUI-master
步骤3:安装依赖包
# 安装PyTorch (NVIDIA GPU版本)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# 安装ComfyUI依赖
pip install -r requirements.txt
# 常见的额外依赖
pip install xformers accelerate
步骤4:启动测试
# 启动ComfyUI
python main.py
# 如果使用GPU
python main.py --force-fp16
⚡ Windows 快速安装脚本
创建一个批处理文件来自动化安装过程:
@echo off
echo 正在安装ComfyUI...
REM 检查Python
python --version >nul 2>&1
if %errorlevel% neq 0 (
echo 错误:未找到Python,请先安装Python 3.8-3.11
pause
exit /b 1
)
REM 创建虚拟环境
python -m venv comfyui_env
call comfyui_env\Scripts\activate.bat
REM 下载ComfyUI
curl -L https://github.com/comfyanonymous/ComfyUI/archive/refs/heads/master.zip -o comfyui.zip
powershell -command "Expand-Archive -Path 'comfyui.zip' -DestinationPath '.'"
REM 安装依赖
cd ComfyUI-master
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
echo 安装完成!运行 python main.py 启动ComfyUI
pause
macOS 平台 ComfyUI 安装教程
🍎 macOS 安装步骤详解
步骤1:Xcode工具安装
# 安装Xcode Command Line Tools
xcode-select --install
# 检查是否安装成功
xcode-select -p
步骤2:Python环境配置
# 使用Homebrew安装Python(推荐)
brew install [email protected]
# 或使用Conda
conda create -n comfyui python=3.10
conda activate comfyui
步骤3:ComfyUI 下载安装
# 下载ComfyUI
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
# 对于Apple Silicon Mac
# 安装MPS支持的PyTorch
pip install torch torchvision torchaudio
# 对于Intel Mac
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 安装其他依赖
pip install -r requirements.txt
步骤4:Apple Silicon 特殊配置
# Apple Silicon Mac 需要额外配置
export PYTORCH_ENABLE_MPS_FALLBACK=1
# 启动ComfyUI(使用MPS加速)
python main.py --force-fp16
🚀 macOS 一键安装脚本
#!/bin/bash
echo "开始安装ComfyUI for macOS..."
# 检查系统架构
ARCH=$(uname -m)
echo "检测到系统架构: $ARCH"
# 检查Python
if ! command -v python3 &> /dev/null; then
echo "错误:未找到Python3,请先安装"
exit 1
fi
# 创建虚拟环境
python3 -m venv comfyui_env
source comfyui_env/bin/activate
# 下载ComfyUI
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
# 根据架构安装对应的PyTorch
if [[ "$ARCH" == "arm64" ]]; then
echo "安装Apple Silicon版本的PyTorch..."
pip install torch torchvision torchaudio
export PYTORCH_ENABLE_MPS_FALLBACK=1
else
echo "安装Intel版本的PyTorch..."
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
fi
# 安装依赖
pip install -r requirements.txt
echo "安装完成!运行以下命令启动:"
echo "source comfyui_env/bin/activate"
echo "cd ComfyUI"
echo "python main.py"
Linux 平台 ComfyUI 安装教程
🐧 Linux 安装步骤详解
步骤1:系统依赖安装
# Ubuntu/Debian系统
sudo apt update
sudo apt install python3 python3-pip python3-venv git build-essential cmake
# CentOS/RHEL系统
sudo yum install python3 python3-pip git gcc gcc-c++ cmake
# Arch Linux
sudo pacman -S python python-pip git base-devel cmake
步骤2:ComfyUI 下载与环境配置
# 创建工作目录
mkdir ~/comfyui_workspace
cd ~/comfyui_workspace
# 克隆代码
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
步骤3:NVIDIA GPU 支持配置
# 检查NVIDIA驱动
nvidia-smi
# 安装CUDA版本的PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# 安装ComfyUI依赖
pip install -r requirements.txt
# 安装xformers加速(可选)
pip install xformers
步骤4:CPU模式安装
# 如果没有GPU,安装CPU版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 安装依赖
pip install -r requirements.txt
🔧 Linux 系统服务配置
创建systemd服务以便后台运行:
# /etc/systemd/system/comfyui.service
[Unit]
Description=ComfyUI Service
After=network.target
[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username/comfyui_workspace/ComfyUI
Environment=PATH=/home/your_username/comfyui_workspace/ComfyUI/venv/bin
ExecStart=/home/your_username/comfyui_workspace/ComfyUI/venv/bin/python main.py --listen 0.0.0.0 --port 8188
Restart=always
[Install]
WantedBy=multi-user.target
# 启用服务
sudo systemctl enable comfyui
sudo systemctl start comfyui
# 检查状态
sudo systemctl status comfyui
ComfyUI 安装常见错误速查表
🚨 错误诊断与解决方案
错误类型 | 错误信息 | 解决方案 | 平台 |
---|---|---|---|
Python版本 | Python 3.12 not supported |
降级到Python 3.8-3.11 | 全平台 |
CUDA版本 | CUDA out of memory |
使用--force-fp16 参数 |
Windows/Linux |
依赖冲突 | No module named 'torch' |
重新安装PyTorch | 全平台 |
权限问题 | Permission denied |
使用管理员权限或sudo | Windows/Linux |
网络问题 | Connection timeout |
使用国内镜像源 | 全平台 |
🔍 详细错误解决方案
错误1:PyTorch安装失败
# 清理现有环境
pip uninstall torch torchvision torchaudio -y
# 使用国内镜像安装
pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 或使用清华源
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 -i https://pypi.tuna.tsinghua.edu.cn/simple/
错误2:显存不足
# 在main.py启动时添加参数
python main.py --force-fp16 --highvram
# 极端情况下使用CPU模式
python main.py --cpu
错误3:端口占用
# 检查端口占用
netstat -an | grep 8188
# 使用其他端口启动
python main.py --port 8189
ComfyUI 安装验证与测试
✅ 安装成功验证脚本
创建一个测试脚本来验证ComfyUI是否正确安装:
#!/usr/bin/env python3
"""
ComfyUI安装验证脚本
"""
import sys
import subprocess
import importlib
import requests
import time
def check_python_version():
"""检查Python版本"""
version = sys.version_info
print(f"Python版本: {version.major}.{version.minor}.{version.micro}")
if version.major != 3 or not (8 <= version.minor <= 11):
print("❌ Python版本不兼容,推荐使用3.8-3.11")
return False
print("✅ Python版本兼容")
return True
def check_dependencies():
"""检查关键依赖包"""
required_packages = ['torch', 'torchvision', 'PIL', 'numpy']
for package in required_packages:
try:
importlib.import_module(package)
print(f"✅ {package} 已安装")
except ImportError:
print(f"❌ {package} 未安装")
return False
return True
def check_gpu_support():
"""检查GPU支持"""
try:
import torch
if torch.cuda.is_available():
gpu_count = torch.cuda.device_count()
gpu_name = torch.cuda.get_device_name(0)
print(f"✅ CUDA可用,GPU数量: {gpu_count}")
print(f" GPU型号: {gpu_name}")
return True
elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
print("✅ MPS可用 (Apple Silicon)")
return True
else:
print("⚠️ GPU不可用,将使用CPU模式")
return False
except Exception as e:
print(f"❌ GPU检查失败: {e}")
return False
def test_comfyui_startup():
"""测试ComfyUI启动"""
print("正在测试ComfyUI启动...")
# 启动ComfyUI进程
process = subprocess.Popen([
sys.executable, "main.py", "--cpu"
], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
# 等待启动
time.sleep(10)
try:
# 测试API连接
response = requests.get("http://localhost:8188", timeout=5)
if response.status_code == 200:
print("✅ ComfyUI启动成功")
return True
else:
print(f"❌ ComfyUI响应异常: {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"❌ 无法连接到ComfyUI: {e}")
return False
finally:
process.terminate()
def main():
"""主函数"""
print("=== ComfyUI安装验证 ===\n")
checks = [
("Python版本", check_python_version),
("依赖包", check_dependencies),
("GPU支持", check_gpu_support),
("ComfyUI启动", test_comfyui_startup)
]
passed = 0
total = len(checks)
for name, check_func in checks:
print(f"\n检查 {name}...")
if check_func():
passed += 1
print(f"\n=== 验证结果 ===")
print(f"通过: {passed}/{total}")
if passed == total:
print("🎉 ComfyUI安装完全成功!")
print("\n下一步:")
print("1. 下载SD模型文件到 models/checkpoints/ 目录")
print("2. 运行 python main.py 启动ComfyUI")
print("3. 访问 http://localhost:8188 开始使用")
else:
print("⚠️ 部分检查未通过,请根据上述提示进行修复")
if __name__ == "__main__":
main()
🔧 API连接测试
对于无法本地部署的用户,可以测试云端API连接:
import requests
import json
def test_comfyui_api():
"""测试ComfyUI API连接"""
# 简单的工作流测试
test_workflow = {
"3": {
"inputs": {"seed": 123, "steps": 10, "cfg": 7.0},
"class_type": "KSampler"
}
}
try:
# 测试云端API连接
response = requests.post(
"https://vip.apiyi.com/v1/comfyui/test",
json={"workflow": test_workflow},
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
timeout=30
)
if response.status_code == 200:
print("✅ 云端API连接成功")
print(f"响应时间: {response.elapsed.total_seconds():.2f}秒")
return True
else:
print(f"❌ API响应错误: {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"❌ API连接失败: {e}")
return False
# 运行测试
if __name__ == "__main__":
test_comfyui_api()
💡 ComfyUI 安装最佳实践
🎯 推荐安装策略
用户类型 | 推荐方案 | 理由 | 备选方案 |
---|---|---|---|
新手用户 | 云端API体验 | 零配置,快速上手 | Portable版本 |
轻度用户 | Conda环境安装 | 环境隔离,便于管理 | Docker部署 |
重度用户 | 源码编译安装 | 性能最优,可定制 | 自建服务器 |
开发者 | Git源码 + 虚拟环境 | 便于调试和贡献 | API集成开发 |
🔄 环境管理最佳实践
# 1. 使用版本管理工具
conda create -n comfyui-stable python=3.10
conda create -n comfyui-dev python=3.11
# 2. 定期备份环境
conda env export > comfyui-environment.yml
# 3. 一键恢复环境
conda env create -f comfyui-environment.yml
# 4. 清理无用依赖
pip-autoremove -y
conda clean --all
❓ ComfyUI 安装常见问题
Q1: 安装过程中出现网络超时怎么办?
网络问题是安装过程中最常见的困扰,解决方案:
# 1. 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 2. 配置pip永久镜像
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
# 3. 手动下载依赖包
wget https://download.pytorch.org/whl/cu121/torch-xxx.whl
pip install torch-xxx.whl
# 4. 使用代理
pip install --proxy http://proxy:port package_name
如果本地安装仍有困难,建议优先考虑云端API方案,比如通过API易等平台直接调用ComfyUI功能,避免本地环境配置的复杂性。
Q2: 我的显卡显存不够,ComfyUI还能用吗?
显存不足的解决方案:
# 1. 启用低精度模式
python main.py --force-fp16
# 2. 启用CPU卸载
python main.py --force-fp16 --highvram
# 3. 完全CPU模式
python main.py --cpu
# 4. 使用模型分割
python main.py --force-fp16 --lowvram
推荐配置对照表:
- 4GB显存:使用
--lowvram
参数 - 6GB显存:使用
--force-fp16
参数 - 8GB显存以上:正常启动
- 无显卡:使用
--cpu
参数或云端API
Q3: Windows Defender误报病毒怎么处理?
这是ComfyUI安装过程中的常见问题:
-
临时解决:
- 将ComfyUI文件夹添加到Windows Defender排除列表
- 设置 -> 更新和安全 -> Windows安全中心 -> 病毒和威胁防护
-
永久解决:
# 以管理员身份运行PowerShell Add-MpPreference -ExclusionPath "C:\ComfyUI" Add-MpPreference -ExclusionProcess "python.exe"
-
验证排除:
Get-MpPreference | Select-Object -ExpandProperty ExclusionPath
📚 延伸阅读与进阶配置
🛠️ 高级配置选项
配置参数 | 功能说明 | 使用场景 |
---|---|---|
--listen 0.0.0.0 |
允许外部访问 | 局域网共享 |
--port 8188 |
自定义端口 | 避免端口冲突 |
--cuda-device 0 |
指定GPU设备 | 多GPU环境 |
--disable-metadata |
禁用元数据 | 隐私保护 |
🔗 相关资源
资源类型 | 推荐内容 | 获取方式 |
---|---|---|
官方文档 | ComfyUI安装指南 | https://github.com/comfyanonymous/ComfyUI |
社区支持 | 技术讨论论坛 | Reddit r/ComfyUI |
云端服务 | API易ComfyUI接口 | https://help.apiyi.com |
视频教程 | 安装演示视频 | YouTube、B站 |
🎯 总结与建议
ComfyUI的安装虽然涉及多个步骤,但只要按照正确的流程,绝大多数问题都可以顺利解决。关键在于选择适合自己的安装方式和做好环境准备。
核心要点回顾:
- 环境准备:确保Python版本兼容(3.8-3.11)
- 依赖安装:根据硬件选择合适的PyTorch版本
- 错误处理:遇到问题及时查阅错误速查表
- 性能优化:根据硬件配置选择合适的启动参数
最终建议:
- 新手用户:优先尝试云端API,快速体验功能
- 技术用户:本地安装配合云端API,灵活使用
- 企业用户:考虑私有化部署或混合云方案
无论选择哪种安装方式,重要的是先跑通基础流程,再逐步深入学习高级功能。结合本地部署和云端API的优势,可以获得最佳的使用体验。
📝 作者简介:资深AI应用开发者,专注ComfyUI部署与优化。定期分享安装踩坑经验和性能调优技巧,搜索"API易"可找到更多ComfyUI云端使用方案。
🔔 技术交流:欢迎在评论区分享安装过程中的问题和解决方案,共同完善ComfyUI生态环境。