Standalone ComfyUI node pack for RealRestorer image restoration.
Special thanks to CCP6 for support and community contribution.
This repository is a ComfyUI integration built on top of the official RealRestorer release:
- Project page: https://yfyang007.github.io/RealRestorer/
- Paper: https://arxiv.org/abs/2603.25502
- Official repository: https://github.com/yfyang007/RealRestorer
- Hugging Face model: https://huggingface.co/RealRestorer/RealRestorer
- Hugging Face benchmark: https://huggingface.co/datasets/RealRestorer/RealIR-Bench
- Hugging Face demo: https://huggingface.co/spaces/dericky286/RealRestorer-Demo
No vendored diffusers fork. All model code is self-contained. Safe to install into any existing ComfyUI environment without breaking dependencies.
The official RealRestorer repo requires a patched fork of diffusers that will
break existing ComfyUI environments. This node pack reimplements the full pipeline
from scratch using only standard PyTorch, transformers, einops, and safetensors.
If you want the original inference code, benchmark pipeline, or paper materials, please use the official RealRestorer repository linked above.
Everything is already in a standard ComfyUI venv. No pip install needed.
- Clone or copy into
ComfyUI/custom_nodes/:
cd ComfyUI/custom_nodes/
git clone <this-repo> ComfyUI-RealRestorer
- Download the model (~42GB) into
ComfyUI/models/RealRestorer/:
cd ComfyUI/models/
mkdir -p RealRestorer
cd RealRestorer
huggingface-cli download RealRestorer/RealRestorer --local-dir .
Expected layout:
ComfyUI/models/RealRestorer/
transformer/ (safetensors + config.json)
vae/ (safetensors + config.json)
text_encoder/ (Qwen2.5-VL-7B weights)
processor/ (tokenizer files)
- Restart ComfyUI. The nodes appear under the RealRestorer category.
| Setting | Default | Description |
|---|---|---|
| model | auto-detected | Scans models/RealRestorer/ for valid bundles |
| precision | bfloat16 | Paper default. float16 uses less VRAM |
| keep_model_loaded | true | Keep in memory between runs |
| Setting | Default | Description |
|---|---|---|
| task_preset | General Restore | Pick from 10 restoration tasks or "Custom" |
| instruction | (empty) | Only used when task_preset is "Custom" |
| seed | 42 | Paper default |
| steps | 28 | Paper default (demo range: 12-40) |
| guidance_scale | 3.0 | Paper default (demo range: 1.0-6.0) |
| size_level | 1024 | Processing resolution (see tooltip) |
| device_strategy | auto | auto / full_gpu / offload_to_cpu / sequential_offload |
At 1024x1024 with bfloat16:
| Strategy | Peak VRAM | Speed | Recommended for |
|---|---|---|---|
| full_gpu | ~34 GB | Fastest | 48GB+ cards |
| offload_to_cpu | ~24 GB peak | Moderate | 26-48GB cards |
| sequential_offload | Fills available | Near offload_to_cpu on 24GB | 24GB cards (3090/4090/5090) |
auto picks full_gpu for >40GB, offload_to_cpu for >26GB, or
sequential_offload otherwise.
The key difference between offload_to_cpu and sequential_offload is not
speed -- it is whether the card can run it at all. offload_to_cpu loads
the full ~24GB transformer to GPU at once, which OOMs on 24GB cards.
sequential_offload only loads what fits.
The transformer (~12B params, ~24GB in bf16) is too large to fit on a 24GB card all at once. Sequential offload loads only the lightweight parts (embedders, connector, final layer: ~1-2GB) to GPU, then pre-loads as many of the 57 transformer blocks as will fit in remaining VRAM. Blocks that don't fit are streamed from CPU one at a time during each denoising step.
On a 24GB card (after text encoder is offloaded): ~18-20GB free for blocks, each block ~400MB, so ~45 of 57 blocks stay on GPU permanently. Only ~12 blocks need streaming per step, which is much faster than streaming all 57.
On a 48GB+ card: all 57 blocks fit, so sequential_offload runs at nearly the same speed as offload_to_cpu with no streaming overhead.
The console log shows exactly how many blocks were pre-loaded vs streamed.
- RealRestorer official repo: https://github.com/yfyang007/RealRestorer
- RealRestorer project page: https://yfyang007.github.io/RealRestorer/
- RealRestorer paper: https://arxiv.org/abs/2603.25502
- RealRestorer Hugging Face model: https://huggingface.co/RealRestorer/RealRestorer
- RealRestorer RealIR-Bench: https://huggingface.co/datasets/RealRestorer/RealIR-Bench
- RealRestorer demo: https://huggingface.co/spaces/dericky286/RealRestorer-Demo
- Base model: Step1X-Edit by StepFun AI
- ComfyUI implementation: Built with Claude (Anthropic)
If this ComfyUI integration is useful, please also cite the official RealRestorer paper:
@misc{yang2026realrestorergeneralizablerealworldimage,
title={RealRestorer: Towards Generalizable Real-World Image Restoration with Large-Scale Image Editing Models},
author={Yufeng Yang and Xianfang Zeng and Zhangqi Jiang and Fukun Yin and Jianzhuang Liu and Wei Cheng and jinghong lan and Shiyu Liu and Yuqi Peng and Gang YU and Shifeng Chen},
year={2026},
eprint={2603.25502},
archivePrefix={arXiv},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2603.25502},
}