Face Detailer (Max Faces)

Every face detailer does the same four things: detect, crop, re-render at a sane resolution, paste back. The whole category is automatic inpainting, and it exists because a face occupying 70 pixels of a 1024 frame has no latent budget and comes out as a smear no matter how good the checkpoint is.

Impact Pack's FaceDetailer owns this loop in ComfyUI, and it works. It also has two long-standing annoyances: two dozen inputs, and the clone problem - every detected region re-renders on the same seed, so a crowd of twelve people comes back as a room of the same person. Donut's DonutFaceDetailer is a fork that keeps the Impact machinery and changes the parts people complain about. Crucially, it still is Impact Pack underneath - it imports impact.core and friends at execution time, and raises a clear error if the pack is missing rather than quietly disappearing from the node list.

What's different

Three things, and they're the reason to pick it over stock FaceDetailer:

max_faces. Detection returns everything the YOLO found, including the blurry strangers in the background. This node filters to segments with a non-empty mask, sorts them by bounding-box area, and keeps only the top max_faces - largest first, default 2. max_faces: 1 is the single-portrait case; raise it when you actually have a group shot and know how many faces are in it.

Megapixel sizing. resolution is an equivalent square target, not an edge length: the crop is scaled to hit that total pixel count with its aspect preserved, then the canvas is snapped to 64-pixel multiples. max_resolution caps the long edge (0 = no cap). This is more predictable VRAM-wise than edge-based guide sizing, which is what the docstring says it's for.

Edit mode and NAG. With edit_mode on, each detected face gets Krea 2 identity-edit conditioning instead of a plain img2img pass; face_reference supplies the identity, face_reference_b swaps to extracting from a second subject image, and vary_seed_per_face gives each face its own seed offset. NAG - a ComfyUI extension that restores negative prompting on guidance-distilled models by intervening in attention - is available through the nag_* inputs and needs the separate krea2-nag pack installed.

Inputs that matter

Wire image, model, clip, vae, positive, negative, and bbox_detector (an UltralyticsDetectorProvider from Impact Subpack). Then:

• resolution - 1024 default. For a face crop, that's generous; 768 is fine for most work.
• denoise - 0.5 default. This is the dial that decides "sharpen" versus "new face." 0.3–0.4 if the face was already decent.
• max_faces - as above.
• bbox_threshold - 0.5. Raise it if the detector is chasing faces in clouds.
• bbox_crop_factor - 3.0, how much context around the box goes into the crop. More context means a more coherent re-render and a more visible seam.
• feather (5) and, in the optional group, noise_mask_feather (20) - the seam dials.
• guide_size_for, cycle, drop_size, sampler_name/scheduler/steps/cfg/seed - inherited Impact semantics; cycle runs multiple refinement rounds, and the implementation keeps intermediate rounds in latent space, decoding once at the end.

Optional extras worth knowing: sam_model_opt and segm_detector_opt refine the bbox into a polygon (fewer rectangular seams), detailer_hook, inpaint_model, scheduler_func_opt, wildcard, turbo_mode, and the nag_* family.

Outputs

image is the recomposited full frame - that's the one you chain onward. cropped_refined and cropped_enhanced_alpha are lists of the individual processed crops (the alpha version has the paste mask baked in), mask is the combined detection mask, detailer_pipe feeds other Impact nodes, and cnet_images is Impact's ControlNet-compatible crop list. Most workflows only use image.

Install

ComfyUI Manager, search DonutNodes, or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/DonutsDelivery/ComfyUI-DonutNodes.git donutnodes
cd donutnodes
python -m pip install -r requirements.txt

You also need ComfyUI Impact Pack and Impact Subpack, and the detector weights: face_yolov8m.pt into models/ultralytics/bbox/, plus sam_vit_b_01ec64.pth in models/sams/ if you use the SAM path. Those are the same Bingsu/adetailer YOLO weights A1111's ADetailer uses - nothing exotic, but nothing bundled either.

Troubleshooting

"DonutFaceDetailer requires a working ComfyUI Impact Pack." That's the execution-time import check firing. Repair Impact Pack through Manager and restart.

"DonutFaceDetailer found no face in face_reference." Edit mode is on and the detector couldn't find a face in your identity image. Use a clear, front-facing shot; bbox_threshold down if it's a hard one.

Clones. If you have more than one face in frame and they're converging, turn on vary_seed_per_face, or prompt for distinct faces before the pass.

Rectangular seams. Swap the bbox path for a segmentation detector and raise noise_mask_feather.

Order of operations. Detail at native resolution, then upscale. Doing it the other way bakes the mangled face into more pixels and then costs you more to fix.

One last thing, straight from the Impact Pack's history: the Ultralytics package that powers every YOLO detector in this pipeline is AGPL-3.0 and had a poisoned release in December 2024 that shipped a cryptominer to ComfyUI users through exactly this style of node. Pin your version.