Roop (Improved)

Want to stamp one person's face onto a generated image in a single node, no training, no LoRA, no GPU muscle? That's exactly what Roop (Improved) does. It's the ComfyUI port of the original A1111 roop script, and while it's been dormant since 2023, it's still the fastest way to take a face you already have and glue it onto whatever your sampler just drew.

Here's the key thing to understand before you wire it in: roop is not a generative identity tool. InstantID, PuLID, and IP-Adapter FaceID all condition the diffusion model so it draws a face that resembles your reference. Roop is the opposite - a post-processing pixel swap. It detects a face in your generated image, detects a face in your reference, and literally copies the identity onto the target region after generation. That's why it's so fast and so reliable: it's not fighting the sampler, it's fixing the result. A common combo is FaceID or IP-Adapter to get "80% there" and roop to finish the likeness.

How it works

Under the hood it's the InsightFace stack, the same backbone behind ReActor, FaceFusion, and half the identity tools in the ecosystem. First, buffalo_l (an ArcFace model pack, ~326 MB) detects and embeds both faces. Then the actual swap is done by inswapper_128.onnx - a small model whose output is a hard 128×128. That ceiling is why swapped faces can look a touch soft compared to the rest of a high-res image; nobody's fixed it because the maintainers deliberately keep the free model frozen and point paying users at their own service. If a face isn't found at 640px detection, the node retries at 320px, so small or distant faces still get caught.

Two more things worth knowing. It runs on CPU only - no CUDA, but the model is so small you won't notice. And it processes whole image batches, so you can feed it video frames and it'll swap every one with the same reference face.

The inputs that matter

Only a handful, and the defaults are sane for a first run:

• image - the target: the face(s) you want replaced.
• reference_image - the face you want to become. One clean, front-facing photo works best.
• swap_model - a dropdown of .onnx/.pth models in the pack's models/roop folder; after install there's just inswapper_128.onnx.
• faces_index - which face(s) in the target to swap, comma-separated and starting at 0 ("0,2" swaps the first and third). Default "0".
• reference_faces_index - which face in the reference image to use. Default "0".
• The face_order / reverse_order pair (and their reference_ twins) let you control how faces are numbered when an image has several: left to right, up to down, or largest to smallest. This is what makes it "Improved."
• console_logging_level - 0 to 2. Crank it to 2 when something's not swapping; the node tells you exactly which faces it found.

Output: a single IMAGE of the same batch size, ready to wire into a VAE decode or a Save Image.

Installing it

The ComfyUI Manager route is easiest: search "ComfyUI roop" and install. Otherwise:

cd ComfyUI/custom_nodes
git clone https://github.com/ssitu/ComfyUI_roop
# Windows portable: run install.bat inside the folder
# everything else: activate your venv, then
python install.py

Then restart ComfyUI. Two gotchas before you even start. The README warns you need the Visual Studio C++ Build Tools on Windows - insightface==0.7.3 is pinned here, the era before InsightFace 1.0 dropped the C++ build requirement, so a modern install can still force a source build. And install downloads roughly 850 MB of models (the inswapper plus buffalo_l), so the first run looks broken while it silently grabs a third of a gigabyte.

Common issues

• Nothing happens, no error. A face wasn't detected - the swap no-ops silently. Set logging to 2 and check "No source face found" / "No target face found" in the console. Note this port has no built-in content filter; the "NSFW check" in the original A1111 README isn't in this code, so a silent no-op is a detection problem, not a filter.
• inswapper_128.onnx missing. The model download failed or went to the wrong folder; make sure it's at custom_nodes/ComfyUI_roop/models/roop/.
• Install conflicts. The pins (insightface==0.7.3, onnxruntime==1.15.0) are old and can fight with other packs' requirements. If things break after installing, that's the first suspect.

One honest caveat: this pack is unmaintained, and if you want an actively developed successor with face-restore and upscaling built in, the community has moved to ReActor. But for a dead-simple, does-one-thing face swap, Roop (Improved) still works exactly as advertised.