UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.
Python computer-visiondeep-learningface-alignmentface-analysisface-anonymizationface-anti-spoofingface-attributesface-detectionface-meshface-parsingface-quality-assessmentface-recognitionface-segmentationface-trackingfacial-landmarksgaze-estimationhead-pose-estimationonnxruntimeportrait-mattingpython
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-imageto 0.26 and removed the fallback for older versions.
Security
- Updated locked
pillowto 13.0.0, along withcertifi,filelock,gitpythonandvirtualenv, to clear open security advisories.
4.1.0 - 2026-10-15
Changed
FaceAnalyzer()now defaults to RetinaFaceMNET_V2+ EdgeFaceXXSinstead of SCRFD500M_KPS+ ArcFaceMNET. Pass the old models explicitly to keep using them.
Added
- AdaFace
IR_50weights (WebFace4M, 166 MB): 95.44% IJB-B, 96.98% IJB-C. More accurate thanIR_18at 1.8x the size.IR_18remains 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
urllib3bumped to 2.8.0 (GHSA-vxq7-64xx-v4gw, GHSA-8988-9cw3-xx77, GHSA-gh4c-6fx4-qh6g) andvirtualenvto 21.14.5 (GHSA-94p9-xgh2-xp45, GHSA-9h9j-4vrj-gf7g, GHSA-p58f-9548-mpm2, GHSA-x78j-v8h9-3j2q). This only changesuv.lock; pip installs already resolve the patchedurllib3. - 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 nowpredictors=. The parameter accepts any list ofBaseAttributesubclasses.Attributeis renamedBaseAttribute, matchingBaseDetector,BaseRecognizer, and the other base classes.- Constructors are keyword-only. Every model class, plus
FaceAnalyzer,BlurFace,EllipticalBlur,FAISS, andBYTETracker, rejects positional arguments.SCRFD(model_name)raisesTypeError; writeSCRFD(model_name=...). - Detector
**kwargsreplaced with explicit options.RetinaFacetakespre_nms_topk,post_nms_topk, anddynamic_size;YOLOv5FaceandYOLOv8Facetakemax_det. Misspelled options now fail instead of being silently ignored. input_sizeremoved fromMobileGaze,HeadPose,BiSeNet, andLandmark106. 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
uint8BGR images. Float or grayscale arrays now raiseValueErrorinstead of silently returning no faces. - Detector capability flags are opt-in.
supports_landmarksandsupports_alignmentdefault toFalseonBaseDetector. 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
BlazeFacedetector: MediaPipe short-range face detector with 6 keypoints.CenterFacedetector.FaceMeshlandmarker: MediaPipe dense 3D face mesh, 468 points or 478 with irises (FaceMeshWeights.V2_478).FaceAttribNetpredictor: eye openness, eyeglasses, sunglasses, and mask probabilities asFaceStateResult, enrichingFacein-place.- Hugging Face mirror fallback for weight downloads when GitHub Releases is unreachable, pinned to an immutable revision.
uniface.common.validate_imageis public for use in custom models.
Fixed
BlazeFaceweighted NMS could loop forever withiou_threshold=1.0or 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_sizeand warn when it disagrees with the ONNX metadata;FaceAttribNetrejects non-square sizes.