ComfyUI Auto-Upscale
Automatically upscale images after ComfyUI finishes generating them, using pure-stdlib Python scripts with built-in infinite-loop prevention and resolution guards.
Prerequisites & Pre-Flight Check
Always verify ComfyUI connectivity and discover installed upscale models first:
python scripts/upscale_image.py --check --server http://127.0.0.1:8188
- If ComfyUI runs on another host or port, pass
--server http://<host>:<port>. - Note the installed models returned under
Installed upscale models. If the user does not specify a model, the scripts auto-select the best installed model (preferring4x-UltraSharp.pth,RealESRGAN_x4plus.pth, etc.). - If the list is empty and the user wants built-in model upscaling, instruct them to place a
.pth/.safetensorsupscale model intoComfyUI/models/upscale_models/(or provide a custom--workflow).
Mode 1: On-Demand Upscaling
Use upscale_image.py when the user wants to upscale already-generated images immediately.
Upscale the latest generated image(s) from ComfyUI history
# Upscale the single most recent non-upscaled image
python scripts/upscale_image.py --latest
# Upscale the latest 4 generated images, downscaling 4x output by 0.5 for a crisp 2x result
python scripts/upscale_image.py --latest 4 --scale-by 0.5
# Use a specific installed model and also save a local copy
python scripts/upscale_image.py --latest 1 --model 4x-UltraSharp.pth --save-dir ./upscaled_out
Upscale specific local image(s) or a folder
# Single or multiple files
python scripts/upscale_image.py --image path/to/gen_0001.png
# Batch upscale all non-upscaled images in a directory
python scripts/upscale_image.py --dir path/to/ComfyUI/output
Preview before running (Validation)
Use --dry-run (and optionally --json for structured output) to verify target images, dimensions, and model selection without queuing anything in ComfyUI:
python scripts/upscale_image.py --latest --dry-run --json
Mode 2: Automatic Post-Generation Watcher
Use watch_upscale.py to run a background daemon that automatically upscales every new image right after ComfyUI finishes generating it.
When starting the watcher via
run_command, setIsDaemon: trueso it stays running in the background while the user generates images in ComfyUI.
Option A: Watch ComfyUI API (Recommended — works locally and remotely)
# Auto-uses WebSocket if websocket-client is installed, otherwise falls back to lightweight /history polling
python scripts/watch_upscale.py --mode comfyui --server http://127.0.0.1:8188
# Force pure-stdlib HTTP polling every 1.5s with a custom prefix and 2x target output
python scripts/watch_upscale.py --mode comfyui --transport poll --interval 1.5 --scale-by 0.5 --prefix "upscaled/{stem}_hd"
Option B: Watch a Local Output Directory
python scripts/watch_upscale.py --mode folder --watch-dir "D:/ComfyUI/output" --server http://127.0.0.1:8188
Reusable Configuration
Copy config.example.json to a local config file (e.g., my_upscale_config.json) and pass --config my_upscale_config.json to either script. CLI flags always override config file values.
Custom Workflows (Ultimate SD Upscale, Tiled Diffusion, SUPIR, etc.)
To use a custom ComfyUI upscale/hires-fix workflow instead of the built-in model upscaler:
python scripts/watch_upscale.py --workflow path/to/upscale_api.json --input-node-id 1
See references/custom-workflows.md for exporting API-format JSON, handling multiple LoadImage nodes, and troubleshooting.
Built-in Safety Guards
- Infinite-Loop Prevention:
- Every submitted upscale job is tagged with
extra_data.auto_upscale_generated = trueand tracked byprompt_id. - Outputs are saved under
upscaled/(filename_prefix = "upscaled/upscaled"by default) and both scripts automatically ignore images inupscaled/or matchingupscaled_prefixes.
- Every submitted upscale job is tagged with
- OOM / Over-Upscale Guard:
- Images whose longest side exceeds
--max-input-side(default2048px) are skipped automatically. Pass--max-input-side 0to disable.
- Images whose longest side exceeds
- No Retroactive Flood on Watcher Startup:
watch_upscale.pysnapshots existing ComfyUI history / folder contents at startup and only processes new images generated afterward.
Verification
- For on-demand runs, confirm the command exits with code
0and prints[UPSCALED] <source> -> upscaled/.... - For watcher runs, run a quick
--once --dry-runtest or check the daemon log forWaiting for new images...and verify that generating one image in ComfyUI triggers exactly one[Upscaled OK]entry without re-triggering.