ComfyUI-RealRestorer

KO | EN

gitlite — search

#hacktoberfest #react #android #machine-learning #deep-learning #linux #docker #nodejs #windows #kubernetes #awesome-list #security #ios #open-source

ComfyUI-RealRestorer

(★ 12)

No description available.

ComfyUI-RealRestorer Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <h2>ComfyUI-RealRestorer: ComfyUI Integration for RealRestorer</h2>
  <p>
    <a href="https://yfyang007.github.io/RealRestorer/"><img src="https://img.shields.io/badge/Project-Page-blue.svg" alt="Project Page"/></a>
    <a href="https://arxiv.org/abs/2603.25502"><img src="https://img.shields.io/badge/arXiv-2603.25502-b31b1b.svg" alt="arXiv Paper"/></a>
    <a href="https://huggingface.co/RealRestorer/RealRestorer"><img src="https://img.shields.io/badge/HuggingFace-Model-yellow.svg" alt="HuggingFace Model"/></a>
    <a href="https://huggingface.co/datasets/RealRestorer/RealIR-Bench"><img src="https://img.shields.io/badge/HuggingFace-RealIR--Bench-green.svg" alt="HuggingFace RealIR-Bench"/></a>
    <a href="https://huggingface.co/spaces/dericky286/RealRestorer-Demo"><img src="https://img.shields.io/badge/HuggingFace-Demo-orange.svg" alt="HuggingFace Demo"/></a>
    <a href="https://github.com/yfyang007/RealRestorer"><img src="https://img.shields.io/badge/GitHub-Official%20Repo-black.svg" alt="Official Repo"/></a>
  </p>
</div>

Standalone ComfyUI node pack for **RealRestorer** image restoration.

Special thanks to [CCP6](https://huggingface.co/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.

## Why This Exists

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.

## Requirements

Everything is already in a standard ComfyUI venv. No `pip install` needed.

## Installation

1. Clone or copy into `ComfyUI/custom_nodes/`:

```
cd ComfyUI/custom_nodes/
git clone <this-repo> ComfyUI-RealRestorer
```

2. 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)
```

3. Restart ComfyUI. The nodes appear under the **RealRestorer** category.

## Nodes

### RealRestorer Model Loader

| 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 |

### RealRestorer Sampler

| 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 |

## VRAM Usage

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.

### How sequential_offload works

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.

## Credits

- 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)

## Citation

If this ComfyUI integration is useful, please also cite the official RealRestorer paper:

```bibtex
@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},
}
```

ComfyUI-RealRestorer

ComfyUI-RealRestorer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ComfyUI-RealRestorer

ComfyUI-RealRestorer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README