hysts/anime-face-detector: 28-Point Anime Face Landmarks in Plain PyTorch

What hysts/anime-face-detector actually returns

The package solves one narrow problem: given an image containing drawn characters, find the faces and place 28 landmark points on each one. The README is explicit that the model detects near-frontal anime faces, which is a scope statement, not a marketing hedge. Profile shots, chins-down angles and heavy occlusion fall outside what the project claims to handle.

The intended user is a Python developer working with illustration or animation frames who needs coordinates, not a classifier. The detector returns a list of predictions, and each prediction carries a bounding box with a confidence score and a keypoint array. The README example shows the box as five floats (x1, y1, x2, y2, score) and the keypoints as 28 rows of three floats (x, y, confidence). Nothing in the output names a character or a person. If you were hoping for identity, this is the wrong layer of the stack.

The 28 points are enough to drive downstream work such as alignment, cropping, or clustering. The repository's own assets show k-means clustering of landmarks detected in real images and the mean image of each cluster, which suggests the author uses the output for that kind of grouping. That is a hint about intended use, not a documented API.

Two detectors and an HRNetV2 landmark head, without OpenMMLab

The architecture is a two-stage pipeline. A face detector (Faster R-CNN or YOLOv3) proposes boxes, and the landmark model (HRNetV2, 28 points) estimates keypoints. The README states both were originally trained with mmdetection and mmpose, and that since v0.1.0 the package runs them without any OpenMMLab runtime dependency.

That last sentence is the real design decision. Rather than depending on mmcv, mmdet and mmpose at runtime, the project vendors the required code under anime_face_detector/_vendor/. The pyproject.toml confirms this: the runtime dependencies are huggingface-hub, numpy, opencv-python-headless, safetensors, torch and torchvision. No OpenMMLab package appears. The vendored code is derived from mmpose v0.29.0, mmdetection v2.28.2 and mmcv v1.7.0, and ruff is configured to skip that directory so diffs against upstream stay reviewable.

The trade-off is visible in the layout. You get a small dependency set and a package that installs from PyPI, but you also carry a frozen copy of three upstream projects inside your environment. When mmpose or mmdetection change, this package does not follow automatically. Weights are stored as safetensors files on the Hugging Face Hub (one repository each for faster-rcnn, yolov3 and hrnetv2) and are downloaded on first use, so the first call needs network access.

Installing anime-face-detector and running a first detection

Installation is a single pip command. The README requires Python 3.12 or later, and notes that PyTorch 2.2.0 or later and torchvision come in as dependencies. If you need a specific CUDA build, the README says to install PyTorch first by following the official instructions, then install this package.

pip install anime-face-detector

The first call downloads the pretrained weights from the Hugging Face Hub as safetensors files. Expect that first run to be slower and to require network access; subsequent runs read from the local cache. The README's usage example uses the yolov3 detector and a local image:

import cv2

from anime_face_detector import create_detector

detector = create_detector("yolov3")
image = cv2.imread("assets/input.jpg")
preds = detector(image)
print(preds[0])

What you should see is a list of dictionaries. Each dictionary has a bbox key holding an array of five float32 values and a keypoints key holding a 28 by 3 array. In the README's printed output the bounding box score is about 0.99987, and the keypoint confidences vary, with several in the 0.8 to 1.0 range. Those confidence values are worth reading before you use the coordinates: a low-confidence landmark is a landmark the model is unsure about.

For an interactive check, the repository ships demo_gradio.py. The README gives these steps, which clone the repo in addition to installing the package and gradio:

pip install anime-face-detector gradio
git clone https://github.com/hysts/anime-face-detector
cd anime-face-detector

python demo_gradio.py

There is also a demo.ipynb in the repository and a public Hugging Face Space if you want to see the output before installing anything.

Where the detector breaks, and what the README does not promise

The most important limitation is stated in the README itself: the model detects near-frontal anime faces. Turn the head and you are outside the trained distribution. Nothing in the documentation describes a fallback for rotated or occluded faces, and no accuracy figures are published, so you cannot estimate the failure rate from the repository alone.

The second limitation is the output type. This is detection and landmark estimation. It does not produce segmentation masks, it does not classify characters, and it does not recognize real people. Several of the related searches around this project point at segmentation and character identification, and the repository does not support either. If your pipeline needs a mask, you are looking at the wrong package.

The third is the dependency floor. Python 3.12 or later is a hard requirement in pyproject.toml. Projects pinned to 3.9, 3.10 or 3.11 cannot install it without upgrading. The pyproject.toml ruff config even notes that tests/golden/generate_golden.py runs only in a legacy Python 3.9 golden-generation environment, which tells you the maintainer is aware of that boundary.

Finally, the first call requires network access to the Hugging Face Hub. In an air-gapped build or a CI job with no egress, the detector will not initialize unless you pre-populate the cache. The README does not document an offline mode.

anime-face-detector versus lbpcascade_animeface and the YOLOv5 anime detector

The README's own links list is the best comparison source, because these are the projects the author considers adjacent. lbpcascade_animeface is a classical cascade classifier. It is small and fast, and it does not need PyTorch at all, but it returns bounding boxes only. There is no landmark model in it, so if you need 28 points for alignment or clustering, it cannot help.

yolov5_anime is a YOLOv5-based detector, also linked from the README with its own Hugging Face Space. It is a single-stage detector like the yolov3 option here, but the difference that matters is the landmark head. Anime Face Detector pairs detection with an HRNetV2 landmark model, so one call gives you boxes and points. With a detector-only project you would need to source and integrate a separate landmark model yourself.

The other linked projects, such as anime_face_landmark_detection and light-anime-face-detector, sit at different points on the speed and accuracy curve. The README does not benchmark them against each other, so treat the list as a starting point for your own evaluation rather than a ranking. What Anime Face Detector offers that the others do not is the packaging: one pip install, safetensors weights, and no OpenMMLab runtime.

Converting old checkpoints and the licence picture

The original .pth checkpoints from the mmdetection and mmpose era remain available in the v0.0.1 release. If you have one of those, or a model you trained yourself with the OpenMMLab tooling, the package ships a console script to convert it. The pyproject.toml maps anime-face-detector-convert to anime_face_detector.convert:main, and the README states the command converts such checkpoints, including self-trained ones, to safetensors. The README does not list the argument names, so read the script's own help output rather than assuming a flag.

Licensing is mixed and worth reading before you ship. The repository code is MIT. The code under anime_face_detector/_vendor/ is derived from mmpose v0.29.0, mmdetection v2.28.2 and mmcv v1.7.0, which are Apache License 2.0, and THIRD_PARTY_LICENSES.md carries the details. MIT and Apache 2.0 are both permissive, but the vendored directory means your distribution includes Apache-licensed code with its own notice requirements. Check THIRD_PARTY_LICENSES.md rather than assuming the MIT badge on the README covers everything.

On maintenance: the repository is not archived, and the last push was on 2026-07-05. The most recent tagged release listed is v0.0.5 from 2021-11-15, while pyproject.toml declares version 0.1.0, so the PyPI version and the GitHub release tags do not line up. Plan for the PyPI package as the upgrade path.

Editorial conclusion

Adopt it if you need bounding boxes and 28 landmarks on near-frontal anime or illustration faces and want a single pip dependency without the OpenMMLab stack. Do not adopt it for profile or heavily occluded faces, for real-photo face recognition, or for segmentation masks, none of which the README claims. Before committing, verify that the first detector call downloads the safetensors weights successfully in your environment and that Python 3.12 or later is available there.

Frequently asked questions

Official sources

1. hysts/anime-face-detector on GitHub
2. Issues
3. License: MIT
4. README
5. Releases