Bing-su/adetailer: Automatic Masking and Inpainting for Stable Diffusion WebUI

What ADetailer actually repairs, and who it is for

Diffusion models are good at whole compositions and bad at small, high-detail regions. A full-body portrait at 512 by 768 pixels gives the face perhaps 40 pixels of height, and the model spends the same number of steps on that face as it does on the background. The result is the familiar smeared eyes, melted fingers and malformed ears. The manual fix is to paint a mask over the face in the img2img tab, raise the resolution, run a second pass, and repeat for each hand.

ADetailer automates that loop. It runs a detection model over the finished image, converts each detection into a mask, crops the region, and sends it through img2img with its own prompt and settings. The README describes it as "an extension for the stable diffusion webui that does automatic masking and inpainting", and notes it is similar to Detection Detailer. The intended user is someone generating batches in stable-diffusion-webui who wants the second pass to happen without opening the img2img tab.

The scope is deliberately narrow. ADetailer does not improve the base generation, does not change the sampler, and does not fix composition. It only finds objects and re-renders them at a better effective resolution.

The detection-to-inpaint pipeline

The flow has four stages, and the README exposes a control for each one.

Detection comes first. The ADetailer model dropdown decides what to look for, and setting it to None disables the extension entirely. The shipped models are YOLOv8 variants: face_yolov8n.pt and face_yolov8s.pt for 2D and realistic faces, hand_yolov8n.pt for hands, and person_yolov8n-seg.pt or person_yolov8s-seg.pt for people, where the seg variants produce masks rather than boxes. Two MediaPipe options, mediapipe_face_full and mediapipe_face_short, cover realistic faces without published mAP figures. The README lists mAP 50 and mAP 50-95 for the YOLO models, so the accuracy difference between the n and s variants is visible before you download anything: face_yolov8n.pt scores 0.660 at mAP 50 and face_yolov8s.pt scores 0.713.

Filtering comes second. The detection model confidence threshold drops weak detections. Mask min/max ratio drops masks whose area falls outside a proportion of the whole image, and the README suggests a min ratio around 0.01 to exclude background objects. Mask only the top k largest keeps the k biggest bounding boxes, with 0 disabling the limit.

Mask preprocessing comes third, and the README states the order explicitly: x, y offset, then erosion or dilation, then merge or invert. Merge mode offers None, which inpaints each mask separately, Merge, which combines all masks into one inpaint region, and Merge and Invert, which combines and inverts before inpainting.

Inpainting comes last. The README says each option corresponds to the equivalent option on the inpaint tab, so the denoising strength and sampler behaviour follow the same rules as a manual img2img pass. The ADetailer prompt and negative prompt fields override the main prompt; if left blank, the README says the input values are reused. Skip img2img is documented as changing the img2img step count to 1, which makes the pass effectively a no-op for img2img-only workflows.

Installing ADetailer from the Extensions tab

The README gives two installation routes, both inside stable-diffusion-webui. The first is the Extensions tab's built-in list. The second, borrowed from the sd-webui-controlnet instructions, installs from a git URL.

Open the Extensions tab, then Install from URL, and paste the repository address.

git clone https://github.com/Bing-su/adetailer.git

The README presents this URL as the value for the "URL for extension's git repository" field rather than as a shell command, so treat the line above as the address to paste. After pressing Install, the README says a message appears reading "Installed into stable-diffusion-webui\extensions\adetailer. Use Installed tab to restart". Then go to the Installed tab, click Check for updates, and click Apply and restart UI. The README is explicit that you must then completely restart the webui including the terminal, and it suggests rebooting the computer if you are unsure what a terminal is.

The repository also carries an install.py at the top level and a preload.py, which is the conventional layout for a webui extension that needs to run setup code at startup. The dependencies declared in pyproject.toml are huggingface-hub, mediapipe>=0.10.13, pydantic<3, rich>=13 and ultralytics>=8.2, and the project requires Python 3.9 or newer. Those five packages are the real installation risk: ultralytics and mediapipe both pull in native code, and a failure there surfaces as a webui startup error rather than a message in the ADetailer panel.

For a first real use, generate one portrait with a visible face, set ADetailer model to face_yolov8n.pt, leave the prompt fields blank so the main prompt is reused, and generate. You should see a second pass applied to the detected face region. If nothing happens, the model dropdown is the first thing to check, because None disables the extension.

Where ADetailer stops being the right tool

The extension is tied to one frontend. Every installation instruction in the README assumes stable-diffusion-webui, and the repository layout reflects that: the top-level entries include controlnet_ext, scripts and a modules exclusion in the ruff configuration, all of which are webui extension conventions. There is no node package, no ComfyUI custom node directory, and no Forge or SwarmUI specific code in the listed top-level entries. If you generate in ComfyUI, the README offers nothing, and you should not expect the extension to load there.

Detection quality is the second boundary. The README publishes mAP figures only for five YOLO checkpoints and leaves the two MediaPipe entries blank. The face models are labelled "2D / realistic face", which is a scope statement: a stylised or heavily illustrated face is not what the numbers describe. If your output is far outside that distribution, the detector may return nothing or return the wrong region, and the mask ratio and confidence controls only filter detections, they do not create them.

The third limit is that ADetailer cannot tell a good face from a bad one. It detects a face and inpaints it, always. On an image where the face is already correct, the second pass can change it, and the only lever is denoising strength on the inpaint options. Batch generation with ADetailer enabled therefore costs time on every image, including the ones that did not need repair.

Finally, the README does not document rollback or version pinning. There is a CHANGELOG.md in the repository, but the install instructions only describe updating through Check for updates and Apply and restart UI. If an update breaks your workflow, the README is silent on how to return to a previous state.

ADetailer against manual img2img masking

The obvious alternative is the img2img tab itself. You paint a mask over the face, set a higher resolution, and run a second pass. That approach has no Python dependencies beyond the webui, works on any frontend that has an img2img tab, and gives you exact control over the region. It also does not scale: ten images means ten masks.

ADetailer trades that control for automation. The mask comes from a detector, so it is consistent across a batch and reproducible, but it is also only as good as the checkpoint. The person_yolov8n-seg.pt model scores 0.782 at mAP 50 for bounding boxes and 0.761 for masks, and the s variant improves both to 0.824 and 0.809. Those gaps are the reason the model dropdown matters more than any other setting.

A second alternative is ControlNet inpainting, which ADetailer supports directly. The README states that ADetailer can use the ControlNet extension with inpaint, scribble, lineart, openpose, tile and depth models, that choosing a model sets the preprocessor automatically, and that it works separately from the model set in the ControlNet extension itself. Selecting Passthrough makes ADetailer use the ControlNet settings configured outside it. This is a genuine difference in approach: plain ADetailer re-renders a region from the prompt alone, while ControlNet-guided ADetailer conditions the re-render on the original region's structure, which matters when you want the identity or pose preserved rather than regenerated.

Maintenance, licence and the cost of updating

The repository is not archived, and the last push was on 2026-09-21, two days before this writing. That is a recent commit, and the presence of a Taskfile.yml, a pre-commit configuration and a tests directory alongside a CHANGELOG.md suggests the project is still being worked on rather than parked. There are no retrieved releases, so versioning appears to happen through commits and the __version__.py file that hatch reads, not through tagged releases you can pin.

That matters for upgrade cost. The README's update path is Check for updates followed by Apply and restart UI, which pulls the current state of the default branch. Because the dependency set includes ultralytics>=8.2 and mediapipe>=0.10.13 as lower bounds rather than pins, an update can change the detection stack underneath you. If you need reproducibility, the version file and the dependency list in pyproject.toml are what you would record.

The licence is AGPL-3.0, declared both in pyproject.toml and in LICENSE.md, with the classifier "License :: OSI Approved :: GNU Affero General Public License v3". This is a copyleft licence with a network clause, and it is stricter than the MIT licence used by many webui extensions. If you are considering bundling ADetailer into a hosted service, the AGPL terms are the first thing to read, and this article is not legal advice. For local, personal generation the practical difference is small.

Editorial conclusion

Adopt ADetailer if you generate in stable-diffusion-webui and want faces, hands or people repaired without manual masking. Do not adopt it if you work in ComfyUI, Forge, SwarmUI or Civitai, because the README documents installation only for the Extensions tab of stable-diffusion-webui and the repository contains no node definitions for those frontends. Before installing, check that your Python is 3.9 or newer, confirm that mediapipe and ultralytics can build on your platform, and read the LICENSE.md file, since AGPL-3.0 terms differ from the MIT licence of many other webui extensions.

Frequently asked questions

Official sources

1. Bing-su/adetailer on GitHub
2. Issues
3. License: AGPL-3.0
4. README