Skip to content

UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.

4.9 KB
Raw Blame

Changelog

Notable changes to UniFace are documented here. Earlier releases are covered by the autogenerated notes on the GitHub releases page.

Unreleased

Changed

  • Dropped Python 3.10 support. UniFace now requires Python 3.11 or newer.
  • Raised the minimum scikit-image to 0.26 and removed the fallback for older versions.

Security

  • Updated locked pillow to 13.0.0, along with certifi, filelock, gitpython and virtualenv, to clear open security advisories.

4.1.0 - 2026-10-15

Changed

  • FaceAnalyzer() now defaults to RetinaFace MNET_V2 + EdgeFace XXS instead of SCRFD 500M_KPS + ArcFace MNET. Pass the old models explicitly to keep using them.

Added

  • AdaFace IR_50 weights (WebFace4M, 166 MB): 95.44% IJB-B, 96.98% IJB-C. More accurate than IR_18 at 1.8x the size. IR_18 remains the default.

Fixed

  • Model licence table no longer implies the MIT licence covers pretrained weights: code and weights licences are now separate columns. InsightFace weights (SCRFD, ArcFace, AgeGender, Landmark106) are non-commercial upstream, EdgeFace is BSD-3-Clause rather than MIT, and AgeGender, Landmark106 and EdgeFace were missing from the table entirely.

Security

  • Locked urllib3 bumped to 2.8.0 (GHSA-vxq7-64xx-v4gw, GHSA-8988-9cw3-xx77, GHSA-gh4c-6fx4-qh6g) and virtualenv to 21.14.5 (GHSA-94p9-xgh2-xp45, GHSA-9h9j-4vrj-gf7g, GHSA-p58f-9548-mpm2, GHSA-x78j-v8h9-3j2q). This only changes uv.lock; pip installs already resolve the patched urllib3.
  • CI and release workflows default to a read-only GITHUB_TOKEN. Jobs that publish keep their explicit write permissions.

4.0.0 - 2026-08-03

Breaking changes

  • Factory functions are gone. create_detector() and its siblings no longer exist. Construct model classes directly.
  • FaceAnalyzer(attributes=...) is now predictors=. The parameter accepts any list of BaseAttribute subclasses.
  • Attribute is renamed BaseAttribute, matching BaseDetector, BaseRecognizer, and the other base classes.
  • Constructors are keyword-only. Every model class, plus FaceAnalyzer, BlurFace, EllipticalBlur, FAISS, and BYTETracker, rejects positional arguments. SCRFD(model_name) raises TypeError; write SCRFD(model_name=...).
  • Detector **kwargs replaced with explicit options. RetinaFace takes pre_nms_topk, post_nms_topk, and dynamic_size; YOLOv5Face and YOLOv8Face take max_det. Misspelled options now fail instead of being silently ignored.
  • input_size removed from MobileGaze, HeadPose, BiSeNet, and Landmark106. These models always resized to the size in the ONNX graph; the parameter had no effect and is gone.
  • Inputs are validated. Detectors and landmarkers require 3-channel uint8 BGR images. Float or grayscale arrays now raise ValueError instead of silently returning no faces.
  • Detector capability flags are opt-in. supports_landmarks and supports_alignment default to False on BaseDetector. Third-party detector subclasses that produce 5-point alignment landmarks must now declare both flags; boxes-only subclasses need no declaration.

Migrating from 3.x

3.x 4.0
create_detector('retinaface', ...) RetinaFace(...)
RetinaFace(RetinaFaceWeights.MNET_V2) RetinaFace(model_name=RetinaFaceWeights.MNET_V2)
FaceAnalyzer(attributes=[AgeGender()]) FaceAnalyzer(predictors=[AgeGender()])
class MyPredictor(Attribute) class MyPredictor(BaseAttribute)
RetinaFace(**{'pre_nms_topk': 1000}) RetinaFace(pre_nms_topk=1000)
HeadPose(input_size=(224, 224)) HeadPose()

Added

  • BlazeFace detector: MediaPipe short-range face detector with 6 keypoints.
  • CenterFace detector.
  • FaceMesh landmarker: MediaPipe dense 3D face mesh, 468 points or 478 with irises (FaceMeshWeights.V2_478).
  • FaceAttribNet predictor: eye openness, eyeglasses, sunglasses, and mask probabilities as FaceStateResult, enriching Face in-place.
  • Hugging Face mirror fallback for weight downloads when GitHub Releases is unreachable, pinned to an immutable revision.
  • uniface.common.validate_image is public for use in custom models.

Fixed

  • BlazeFace weighted NMS could loop forever with iou_threshold=1.0 or a zero-area box; it now always terminates.
  • Face.__repr__ no longer assumes all five face-state fields are set together.
  • Attribute models normalize input_size and warn when it disagrees with the ONNX metadata; FaceAttribNet rejects non-square sizes.