|

Docs

ComfyUI – Installation & Usage Guide

This guide provides step-by-step instructions to install, configure, and use ComfyUI for AI image generation. ComfyUI is a node-based interface for Stable Diffusion, offering greater flexibility and control over the image generation process.

System Requirements

Recommended Hardware

  • GPU: NVIDIA (8GB+ VRAM recommended), AMD (Linux), or Apple Silicon
  • RAM: 16GB or more
  • Disk Space: 20GB+ for installation and models
  • Operating System: Windows 10/11, Linux, or macOS

Required Software

  • Python 3.10–3.12 (3.12 recommended)
  • Git (for repository-based installation)

Installation

Windows

Method 1: Portable Install (Easiest)

  1. Download the portable version of ComfyUI from the releases page.
  2. Extract the ZIP with 7-Zip.
  3. Navigate to the extracted folder.
  4. Run run_nvidia_gpu.bat (for NVIDIA GPUs) or run_cpu.bat (without a GPU).

Method 2: Install via Git

  1. Install Python 3.10–3.12 from the official website.
  2. Install Git from the official website.
  3. Open Command Prompt or PowerShell.
  4. Clone the repository:

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

5‎.‎ Go to the ComfyUI folder:

cd ComfyUI

6.‎ Start ComfyUI:

python main.py

Linux

  1. Install required dependencies:

sudo apt update sudo apt install python3 python3-pip python3-venv git

2.‎ Clone the repository:

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

3.‎ Go to the ComfyUI folder:

cd ComfyUI

4.‎ (Optional) Create a virtual environment:

python3 -m venv venv source venv/bin/activate

5.‎ Start ComfyUI:

python3 main.py

macOS

  1. Install Homebrew (if you don’t have it yet):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Python and Git:

brew install python git

3.‎ Clone the repository:

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

4.‎ Go to the ComfyUI folder:

cd ComfyUI

5.‎ Start ComfyUI:

python3 main.py

Configuring webui-user.bat

To enable the API and other necessary settings, you need to modify the webui-user.bat file (Windows) or create a startup script (Linux/macOS).

Windows

  1. Create or edit the webui-user.bat file in the ComfyUI root folder with the following content:
@echo off

set PYTHON=
set GIT=
set VENV_DIR=
set COMMANDLINE_ARGS=--api --cors-allow-origins=* --listen --server-name 0.0.0.0 --port 8188 --disable-safe-unpickle

call main.py
  1. Save the file and use it to start ComfyUI instead of the default file.

Linux/macOS

  1. Create a start_comfyui.sh file in the ComfyUI root folder:
#!/bin/bash

python3 main.py --api --cors-allow-origins=* --listen --server-name 0.0.0.0 --port 8188 --disable-safe-unpickle
  1. Make the file executable:
chmod +x start_comfyui.sh
  1. Run the script:
./start_comfyui.sh

Downloading Models

ComfyUI does not ship with pre-installed models. You need to download models separately.

Quick Start - Essential Model Download

⚠️ REQUIRED: For image generation, you need at least one checkpoint model.

Recommended starter model (Choose one):

  1. Stable Diffusion 1.5 (Smaller, faster):

2. SDXL Base (Higher quality, requires more VRAM):

  • Download any SDXL model from Civitai
  • Size: ~6-7GB
  • Place in: models/checkpoints/

Method 1: Manual Download

  1. Create the following folders in the ComfyUI root (if they don't already exist):
  • models/checkpoints – For main models (SD 1.5, SDXL, etc.)
  • models/vae – For VAE models
  • models/controlnet – For ControlNet models
  • models/loras – For LoRA models
  1. Download models from sites such as:
  1. Place the downloaded files (.safetensors or .ckpt) into the corresponding folders.

Method 2: ComfyUI Model Manager

  1. Start ComfyUI.
  2. Open the web interface (usually http://127.0.0.1:8188).
  3. Click the menu button (three horizontal lines) in the top-right corner.
  4. Select Manager from the menu.
  5. Use the manager to download models directly.

Running ComfyUI with the API Enabled

To use ComfyUI with your application, you must start it with the --api flag.

Windows

  1. Run the webui-user.bat file you configured earlier.
  2. Wait until the terminal shows:
  3. Running on local URL: http://127.0.0.1:8188

Linux/macOS

  1. Run the start_comfyui.sh script you created earlier:
  2. ./start_comfyui.sh
  3. Wait until the terminal shows:
  4. Running on local URL: http://127.0.0.1:8188

Checking if the API is Working

  1. Open your browser and go to:
  2. http://127.0.0.1:8188/object_info
  3. You should see a JSON response with information about the available nodes in ComfyUI.

Testing Basic Image Generation

  1. Open the ComfyUI Interface:
  2. Go to: http://127.0.0.1:8188
  3. You should see a node-based workflow interface
  4. Load Default Workflow (if needed):
  5. Click the "Load Default" button in the interface
  6. This creates a basic text-to-image generation workflow
  7. Test Image Generation:
  8. Find the "positive" text input node (usually labeled "CLIP Text Encode (Prompt)")
  9. Enter a simple prompt like: "a beautiful sunset over mountains"
  10. Click "Queue Prompt" button
  11. Wait for generation to complete (may take 30-60 seconds on first run)
  12. The generated image should appear in the interface
  13. Verify API Endpoints:
  14. Check queue status: http://127.0.0.1:8188/queue
  15. Check history: http://127.0.0.1:8188/history
  16. These should return JSON responses without errors

Integrating with Your Application

Once ComfyUI is running with the API enabled, your application can connect to it via http://127.0.0.1:8188.

Key Points

  1. ComfyUI must be running before your application tries to connect.
  2. The default port is 8188 (different from Forge/AUTOMATIC1111, which uses 7860).
  3. The API uses node-based JSON workflows.
  4. Your application should send requests to the /prompt endpoint.

Common Troubleshooting

ComfyUI doesn't start

  • Ensure Python is installed correctly.
  • Try running pip install -r requirements.txt in the ComfyUI folder.
  • Check for errors in the console.

Error "CUDA out of memory"

  • Reduce the image size (e.g., 512×512 instead of 1024×1024).
  • Close other applications using the GPU.
  • Add --lowvram to the startup flags.

API not responding

  • Ensure ComfyUI was started with the --api flag.
  • Confirm that port 8188 is not blocked by a firewall.
  • Verify that ComfyUI is running and hasn't crashed.

Models don't appear

  • Check that models are in the correct folders.
  • Restart ComfyUI after adding new models.
  • Verify that file formats are supported (.safetensors, .ckpt).

Integration-Specific Issues

Error: "No images found in ComfyUI output"

  • Ensure at least one checkpoint model is installed in models/checkpoints/
  • Verify the workflow completed successfully in the ComfyUI interface
  • Check that the model is compatible with your hardware (VRAM requirements)
  • Restart ComfyUI after installing new models

Error: "Maximum call stack size exceeded" or "FileReader is not defined"

  • This indicates an integration issue with the calling application
  • Ensure your application uses proper Node.js Buffer handling for image conversion
  • The application should use Buffer.from() instead of browser-specific APIs

Generation takes too long or times out

  • First image generation is slower due to model loading (can take 2-3 minutes)
  • Subsequent generations should be faster (30-60 seconds)
  • Check ComfyUI console for progress indicators
  • For SDXL models, ensure you have 8GB+ VRAM

Workflow errors in ComfyUI interface

  • Red nodes indicate errors in the workflow
  • Common causes: Missing models, incompatible settings, insufficient VRAM
  • Check the console output for specific error messages
  • Try loading the default workflow: Menu → Load Default

Pre-Integration Checklist

Before integrating ComfyUI with your application, ensure:

  • ComfyUI starts without errors
  • At least one checkpoint model is installed in models/checkpoints/
  • API endpoints respond correctly (/object_info, /queue, /history)
  • Basic image generation works in the ComfyUI interface
  • The --api flag is included in your startup command
  • Port 8188 is accessible and not blocked by firewall

Important Notes

  • ComfyUI runs locally on the user's machine, not on a remote server.
  • Performance depends on the user's hardware, especially the GPU.
  • Large models (like SDXL) require more VRAM (8GB+ recommended).
  • The first run may be slower due to initial model loading.
  • At least one checkpoint model is required for image generation to work.
  • The default workflow uses a simple text-to-image setup that works with most models.
  • Generated images are saved in the output folder within ComfyUI directory.

Additional Resources

This guide was created to help users set up and use ComfyUI for AI image generation. If you encounter issues or have questions, consult the official documentation or community resources.