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-installation-guide 图示


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安装过程中的常见问题:

  1. 临时解决

    • 将ComfyUI文件夹添加到Windows Defender排除列表
    • 设置 -> 更新和安全 -> Windows安全中心 -> 病毒和威胁防护
  2. 永久解决

    # 以管理员身份运行PowerShell
    Add-MpPreference -ExclusionPath "C:\ComfyUI"
    Add-MpPreference -ExclusionProcess "python.exe"
    
  3. 验证排除

    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的安装虽然涉及多个步骤,但只要按照正确的流程,绝大多数问题都可以顺利解决。关键在于选择适合自己的安装方式和做好环境准备。

核心要点回顾

  1. 环境准备:确保Python版本兼容(3.8-3.11)
  2. 依赖安装:根据硬件选择合适的PyTorch版本
  3. 错误处理:遇到问题及时查阅错误速查表
  4. 性能优化:根据硬件配置选择合适的启动参数

最终建议

  • 新手用户:优先尝试云端API,快速体验功能
  • 技术用户:本地安装配合云端API,灵活使用
  • 企业用户:考虑私有化部署或混合云方案

无论选择哪种安装方式,重要的是先跑通基础流程,再逐步深入学习高级功能。结合本地部署和云端API的优势,可以获得最佳的使用体验。


📝 作者简介:资深AI应用开发者,专注ComfyUI部署与优化。定期分享安装踩坑经验和性能调优技巧,搜索"API易"可找到更多ComfyUI云端使用方案。
🔔 技术交流:欢迎在评论区分享安装过程中的问题和解决方案,共同完善ComfyUI生态环境。

类似文章