DEHEAD: Anonymization by head detection

Posted on May 30, 2026

I was looking for an anonymization tool for a project I was working on. Most existing tools follow a two step approach: they detect the face, then blur or mask it. However, this can get unreliable in edge cases where the subject moves significantly, turns sideways, or is viewed from above. Therefore, I built this small tool called dehead (inspired by deface). It uses YOLO to detect the entire head region, and masks it accordingly.

About

dehead is a simple command-line tool for automatic anonymization in videos or photos. Inspired from deface. Uses YOLO internally. Pretrained YOLO model sourced from this project. If pretrained model is not available there, you can download it here (community-hosted mirror) as well. Download best.pt and place it under project root.

This project is created for edge cases, where tools like deface fail to anonymize side views or back views of heads.

Demo videos (links)

Installation (using `uv`)

Install uv.
Clone the repo: git clone https://github.com/degD/dehead && cd dehead.
Make sure python3.12 or newer is installed.
Install dependencies with uv sync.
Add bin/ subdirectory to path.
Download and place model weights. See releases.
Run dehead.

Usage

Quick start

If you want to try out anonymizing a video using the default settings, you just need to supply the path to it. For example, if the path to your test video is myvideos/vid1.mp4, run:

$ dehead myvideos/vid1.mp4

This will write the output to the file myvideos/vid1-dehead.mp4.

CLI usage and options summary

To get an overview of usage and available options, run:

$ dehead -h

usage: dehead [--output O] [--thresh T] [--boxes] [--mask-scale M]
              [--replacewith {blur,solid}] [--blur-radius R] 
              [--batch-size B]
              [--version] [--help] [input ...]

Video anonymization by head detection

positional arguments:
  input                 File path(s). It is possible to pass multiple paths.

optional arguments:
  --output O, -o O      Output file name. Defaults to input path + postfix "-dehead".
  --thresh T, -t T      Detection threshold. Default: 0.2.
  --boxes               Use boxes instead of ellipse masks.
  --mask-scale M        Scale factor for face masks, to make sure that masks
                        cover the complete face. Default: 1.2.
  --replacewith {blur,solid}
                        Anonymization filter mode for face regions. "blur"
                        applies a strong gaussian blurring, "solid" draws a
                        solid black box.
  --blur-radius         Blur radius. Default: 15
  --batch-size          Number of images to be loaded into memory for parallel
                        processing. Increasing this number decreases the process
                        time, but increases memory consumption. Default: 16 
                        (3-4GB memory)
  --version, -v         Print version number and exit.
  --help, -h            Show this help message and exit.

Known Issues

Inputs must be files, passing directories is not supported. But you can pass videos and images together.
Explicitly batches files for head detection, which might be slowing down the process slightly.
Video files are processed without keeping the audio.
Generated video files are always re-encoded using mp4v at fixed 30 FPS, independent from source settings. This can increase file size and alter playback duration/speed for non-30 FPS inputs.
Model weights are sourced from a different project, and could be removed in the future if requested. Also, it could perform bad in some cases, or could be too large for others. However, it is planned to train a new model in the future that will hopefully mitigate these problems.
Progress display is missing.

Credits

This project is particularly inspired from deface.
The model weights file is sourced from Head-Detection-Yolov8.

License

MIT