UniFace logo

UniFace is a Python library for face analysis. It provides APIs for face detection, recognition, landmarks, parsing, tracking, attributes, gaze estimation, head pose, anti-spoofing, anonymization, and vector search.

The library is built around a common set of conventions. Detectors return Face objects, recognition models work with the same landmark format, and higher-level APIs such as FaceAnalyzer combine common steps when you do not need to wire each module manually.

Installation

Install the CPU version for regular CPU inference or Apple Silicon:

pip install "uniface[cpu]"

Install the GPU version for NVIDIA CUDA:

pip install "uniface[gpu]"

The extras are separate because onnxruntime and onnxruntime-gpu should not be installed together. Models are downloaded on first use, verified with SHA-256, and cached locally.

Face Detection

import cv2
from uniface.detection import RetinaFace

image = cv2.imread("photo.jpg")
if image is None:
    raise ValueError("Could not read photo.jpg")

detector = RetinaFace()
faces = detector.detect(image)

for face in faces:
    print("confidence:", round(face.confidence, 3))
    print("bbox:", face.bbox)
    print("landmarks:", face.landmarks)

This is the smallest useful example. It loads an image, runs a detector, and prints the bounding box and 5-point landmarks for each face.

For webcam input, the same detector can be used frame by frame:

import cv2
from uniface.detection import RetinaFace
from uniface.draw import draw_detections

detector = RetinaFace()
cap = cv2.VideoCapture(0)

while True:
    ok, frame = cap.read()
    if not ok:
        break

    faces = detector.detect(frame)
    draw_detections(image=frame, faces=faces, vis_threshold=0.6)

    cv2.imshow("UniFace detection", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

For a higher-level pipeline, FaceAnalyzer can run detection, embedding extraction, and optional attributes in one call:

import cv2
from uniface import AgeGender, FaceAnalyzer

image = cv2.imread("photo.jpg")
analyzer = FaceAnalyzer(attributes=[AgeGender()])
faces = analyzer.analyze(image)

for face in faces:
    print(face.bbox, face.sex, face.age)

See the full documentation at yakhyo.github.io/uniface and the source code on GitHub.

What UniFace Includes

Area Models and features
Detection RetinaFace, SCRFD, YOLOv5-Face, YOLOv8-Face
Recognition AdaFace, ArcFace, EdgeFace, MobileFace, SphereFace
Landmarks 5-point detector landmarks, plus 106 / 98 / 68-point models
Tracking BYTETracker-based persistent IDs for video
Parsing BiSeNet semantic face parsing and XSeg masking
Matting MODNet portrait matting for background removal
Attributes Age, gender, race, and emotion
Gaze MobileGaze for gaze direction estimation
Head pose Pitch, yaw, and roll estimation
Anti-spoofing MiniFASNet
Privacy Pixelate, gaussian, blackout, elliptical, and median anonymization
Search Optional FAISS-backed vector store

Notebooks and Demo

The examples can be opened directly in Google Colab:

Notebook Colab Focus
Face Detection Open Detection and 5-point landmarks
Face Alignment Open Alignment for recognition
Face Verification Open Similarity-based identity matching
Face Search Open Searching for a person in group photos
Face Analyzer Open Detection, recognition, and attributes
Face Parsing Open Semantic face segmentation
Face Anonymization Open Face blurring and anonymization
Gaze Estimation Open Gaze direction prediction
Face Segmentation Open XSeg-based masking
Face Vector Store Open FAISS-backed embedding search
Head Pose Estimation Open Pitch, yaw, and roll
Face Recognition Open Recognition without FaceAnalyzer
Portrait Matting Open Background removal and compositing

There is also a live Hugging Face demo at huggingface.co/spaces/yakhyo/uniface.

Library Design

UniFace keeps the individual modules independent, but makes them work together through shared inputs and outputs. You can use only the detector, build a recognition pipeline yourself, or start from FaceAnalyzer when you want the common detection-plus-recognition path.

The library supports macOS, Linux, and Windows, including CPU inference, Apple Silicon, and NVIDIA CUDA through ONNX Runtime providers.