Getting started

This page covers the manual install path that most contributors will use. The desktop app and Windows portable bundle are alternatives intended for end users; both build on top of this same code.

Prerequisites

• Python. 3.10 minimum, 3.12 or 3.13 recommended. 3.14 works for the core, but custom nodes lag behind.
• PyTorch. 2.4+ supported, latest stable preferred. Install from the right wheel for your hardware (CUDA, ROCm, XPU, MPS, DirectML, NPU). The README has hardware-specific install commands.
• Git for cloning, pip for dependencies.
• A reasonable amount of disk space for models — checkpoints alone are commonly 5-25 GB each.

Install

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

# Install PyTorch for your hardware (example: CUDA 13.0)
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

# Install ComfyUI's runtime dependencies
pip install -r requirements.txt

The pinned dependencies live in requirements.txt. The most notable are:

• comfyui-frontend-package — the compiled web frontend bundle
• comfyui-workflow-templates — stock workflow JSON
• comfyui-embedded-docs — in-app docs
• comfy-kitchen, comfy-aimdo — Comfy Org helper packages
• torch, transformers, safetensors, kornia, spandrel — ML stack
• aiohttp, pydantic — server stack
• SQLAlchemy, alembic — database

Drop your checkpoints into models/checkpoints/, VAEs into models/vae/, etc. To share model files with another UI, copy extra_model_paths.yaml.example to extra_model_paths.yaml and edit the search paths.

Run

python main.py

The server listens on 127.0.0.1:8188 by default. Open that URL in a browser. Common flags:

Flag	What it does
--listen [IP[,IP]]	Listen on given addresses (or 0.0.0.0,:: if no value)
--port N	Listen port (default 8188)
--cpu	Run everything on CPU
--lowvram / --novram / --gpu-only	Coarse VRAM hints; usually ComfyUI picks correctly on its own
--preview-method auto|taesd|latent2rgb	Show in-progress sampling previews
--front-end-version Comfy-Org/ComfyUI_frontend@latest	Use a specific frontend release
--enable-manager	Enable ComfyUI-Manager (if comfyui-manager is installed via manager_requirements.txt)
--disable-api-nodes	Disable nodes that talk to paid external APIs
--disable-all-custom-nodes	Skip loading anything in custom_nodes/
--enable-assets	Turn on the asset database and background scanner
--database-url sqlite:///...	Override the default SQLite location

The complete list lives in comfy/cli_args.py. Many flags are mutually exclusive (e.g., the --fp16-unet / --bf16-unet group, the cache mode group, the attention backend group).

First workflow

ComfyUI ships with a default workflow. To try it:

1. Drop a Stable Diffusion checkpoint (e.g., SDXL or SD1.5) into models/checkpoints/.
2. Start ComfyUI: python main.py.
3. Open http://127.0.0.1:8188. The graph that loads has Load Checkpoint → CLIP Text Encode (positive + negative) → KSampler → VAE Decode → Save Image.
4. Pick the checkpoint in the Load Checkpoint node. Click Queue Prompt.

Generated images are written to output/ and registered with the asset system if --enable-assets is on.

Test

There are two test trees:

• tests-unit/ — pytest unit tests that don't need GPU.
• tests/ — integration tests that exercise the server end-to-end.

# Install test dependencies
pip install -r tests-unit/requirements.txt

# Run unit tests
pytest tests-unit

# Lint
ruff check .

The same checks run in CI; see .github/workflows/ and Tooling.

Trouble?

• "Torch not compiled with CUDA" — uninstall torch and reinstall the GPU wheel for your hardware.
• Black images — try --fp32-vae or another VAE precision flag.
• CUDA OOM — try --lowvram, --novram, or split a model with --fp8_e4m3fn-unet.
• "Database is locked" — another ComfyUI process holds the lockfile; pass --database-url sqlite:///path/to/another.db.

For deeper debugging, see Debugging.