Docker¶

Quick Start¶

Requires Docker and an NVIDIA GPU.

docker run --gpus all -p 8188:8188 -v comfyui:/data ghcr.io/umeairt/comfyui:latest

Open http://localhost:8188 — ComfyUI is ready.

That's it. All your data (models, custom nodes, outputs) is stored in the comfyui volume and persists between container restarts or removal.

Windows

Docker Desktop with WSL2 handles GPU passthrough automatically — no extra setup needed with recent NVIDIA drivers (≥ 525.x).

Data Storage¶

You have two options for where your data lives:

Option 1: Docker Volume (recommended)¶

docker run --gpus all --name comfyui -p 8188:8188 -v comfyui:/data ghcr.io/umeairt/comfyui:latest

Docker manages the storage. Data persists until you explicitly delete the volume. Simple and cross-platform.

Option 2: Local Folder¶

docker run --gpus all --name comfyui -p 8188:8188 -v ./comfyui_data:/data ghcr.io/umeairt/comfyui:latest

Data lives in ./comfyui_data/ on your disk — you can see and edit the files directly:

./comfyui_data/
├── models/          ← drop .safetensors files here
├── custom_nodes/    ← installed automatically at first boot
├── output/          ← your generated images
├── input/           ← images you upload to ComfyUI
└── user/            ← ComfyUI settings

Note

If no -v is specified, Docker still creates an anonymous volume automatically (thanks to VOLUME /data in the Dockerfile), so you won't lose data accidentally — but finding that anonymous volume later is harder.

Customization¶

Custom Node Bundles¶

Control which nodes get installed with the NODE_TIER environment variable:

Tier	What's installed	Use Case
`minimal`	ComfyUI-Manager only	Quick testing
`umeairt`	+ UmeAiRT Sync/Toolkit + essentials	UmeAiRT workflows
`full`	+ all community nodes (~34)	Default

docker run --gpus all -p 8188:8188 -v comfyui:/data -e NODE_TIER=minimal ghcr.io/umeairt/comfyui:latest

Change tiers by restarting with a different value — no rebuild needed.

JupyterLab (Cloud / RunPod)¶

A cloud variant adds JupyterLab for remote development:

docker run --gpus all -p 8188:8188 -p 8888:8888 -v comfyui:/data \
  -e JUPYTER_ENABLE=true -e JUPYTER_TOKEN=mysecrettoken \
  ghcr.io/umeairt/comfyui:latest-cloud

ComfyUI → :8188
JupyterLab → :8888

All Environment Variables¶

Variable	Default	Description
`NODE_TIER`	`full`	Custom node bundle (`minimal`, `umeairt`, `full`)
`COMFYUI_ARGS`	`--enable-cors-header`	CLI arguments for ComfyUI (allows RunPod proxy access by default)
`FORCE_UPDATE`	`false`	Force full update on boot (nodes + deps + GPU). Useful after image upgrade.
`JUPYTER_ENABLE`	`false`	Start JupyterLab (cloud variant only)
`JUPYTER_TOKEN`	(empty)	JupyterLab access token
`JUPYTER_PORT`	`8888`	JupyterLab listening port

Docker Compose¶

If you prefer docker compose, clone the repo and use the included docker-compose.yml:

git clone https://gitlab.com/UmeAiRT-Studio/ComfyUI-Auto_installer-Python.git
cd ComfyUI-Auto_installer-Python
docker compose up -d

Edit docker-compose.yml to customize environment variables or switch between Docker volume and local folder storage.

Cloud GPU (RunPod / Vast.ai)¶

The container is optimized for cloud GPU environments where you pay by the minute. The smart boot system minimizes startup time and avoids wasting money on redundant installations.

How it works¶

The entrypoint uses three boot modes:

Mode	When	What happens	Time
First boot	No venv on `/data`	Full install: PyTorch + nodes + optimizations	~5 min
Warm boot	Venv exists, same GPU	Skip everything, launch ComfyUI directly	~10 sec
GPU change	Venv exists, different GPU	Reinstall only GPU optimizations (triton, sage)	~30 sec

The venv and all data are persisted on /data (your Network Volume), so they survive pod restarts and even pod termination + recreation.

RunPod Setup¶

Create a template with image registry.gitlab.com/umeairt-studio/comfyui-auto_installer-python:latest-cloud
Volume mount path: /data
HTTP ports: 8188 (ComfyUI), 8888 (JupyterLab)
Environment variables:
NODE_TIER = full
JUPYTER_ENABLE = true

After updating the Docker image

Add FORCE_UPDATE=true to your environment variables temporarily. This forces a full update on the next boot. Remove it after the first restart to return to fast boot mode.

GPU Change Detection¶

When you switch GPU types between pods (e.g. A100 → L40S → H100), the entrypoint detects the change via nvidia-smi and automatically reinstalls only the GPU-specific packages (SageAttention wheels, Triton, flash-attn). PyTorch itself is CUDA-compatible across NVIDIA GPUs so it does not need reinstallation.

The GPU fingerprint is saved in /data/.gpu_state.

Building Locally¶

# Standard image
docker build -t umeairt/comfyui:latest .

# Cloud image (with JupyterLab)
docker build --build-arg VARIANT=cloud -t umeairt/comfyui:cloud .

Troubleshooting¶

GPU not detected¶

Verify Docker can see your GPU:

docker run --rm --gpus all nvidia/cuda:13.0.2-cudnn-runtime-ubuntu24.04 nvidia-smi

`bash\r: No such file or directory`¶

Shell scripts have Windows line endings. The Dockerfile fixes this automatically, but if you edited entrypoint.sh locally, ensure it uses LF endings.