UniFace: A Unified Face Analysis Library for Python

[!NOTE] UniFace is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.

Features

Visual Examples

Face Detection	Gaze Estimation
Head Pose Estimation	Age & Gender
Face Verification
106-Point Landmarks	98-Point Landmarks (PIPNet)
Face Parsing
Face Segmentation
Portrait Matting
Face Anonymization

Installation

CPU / Apple Silicon

pip install uniface[cpu]

GPU support (NVIDIA CUDA)

pip install uniface[gpu]

Why separate extras? onnxruntime and onnxruntime-gpu conflict when both are installed — they own the same Python namespace. Installing only the extra you need prevents that conflict entirely.

From source (latest version)

git clone https://github.com/yakhyo/uniface.git
cd uniface && pip install -e ".[cpu]"   # or .[gpu] for CUDA

FAISS vector store

pip install faiss-cpu   # or faiss-gpu for CUDA

Optional dependencies

• Emotion model uses TorchScript and requires torch: pip install torch (choose the correct build for your OS/CUDA)
• YOLOv5-Face and YOLOv8-Face support faster NMS with torchvision: pip install torch torchvision then use nms_mode='torchvision'

Model Downloads and Cache

Models are downloaded automatically on first use and verified via SHA-256.

Default cache location: ~/.uniface/models

Override with the programmatic API or environment variable:

from uniface.model_store import get_cache_dir, set_cache_dir

set_cache_dir('/data/models')
print(get_cache_dir())  # /data/models

export UNIFACE_CACHE_DIR=/data/models

Quick Example (Detection)

import cv2
from uniface.detection import RetinaFace

detector = RetinaFace()

image = cv2.imread("photo.jpg")
if image is None:
    raise ValueError("Failed to load image. Check the path to 'photo.jpg'.")

faces = detector.detect(image)

for face in faces:
    print(f"Confidence: {face.confidence:.2f}")
    print(f"BBox: {face.bbox}")
    print(f"Landmarks: {face.landmarks.shape}")

Example (Face Analyzer)

import cv2
from uniface import FaceAnalyzer

# Zero-config: uses SCRFD (500M) + ArcFace (MobileNet) by default
analyzer = FaceAnalyzer()

image = cv2.imread("photo.jpg")
if image is None:
    raise ValueError("Failed to load image. Check the path to 'photo.jpg'.")

faces = analyzer.analyze(image)

for face in faces:
    print(face.bbox, face.embedding.shape if face.embedding is not None else None)

With attributes:

from uniface import FaceAnalyzer, AgeGender

analyzer = FaceAnalyzer(predictors=[AgeGender()])
faces = analyzer.analyze(image)

for face in faces:
    print(f"{face.sex}, {face.age}y, embedding={face.embedding.shape}")

Example (Portrait Matting)

import cv2
import numpy as np
from uniface.matting import MODNet

matting = MODNet()

image = cv2.imread("portrait.jpg")
matte = matting.predict(image)  # (H, W) float32 in [0, 1]

# Transparent PNG
rgba = cv2.cvtColor(image, cv2.COLOR_BGR2BGRA)
rgba[:, :, 3] = (matte * 255).astype(np.uint8)
cv2.imwrite("transparent.png", rgba)

# Green screen
matte_3ch = matte[:, :, np.newaxis]
bg = np.full_like(image, (0, 177, 64), dtype=np.uint8)
result = (image * matte_3ch + bg * (1 - matte_3ch)).astype(np.uint8)
cv2.imwrite("green_screen.jpg", result)

Jupyter Notebooks

Example	Colab	Description
01_face_detection.ipynb		Face detection and landmarks
02_face_alignment.ipynb		Face alignment for recognition
03_face_verification.ipynb		Compare faces for identity
04_face_search.ipynb		Find a person in group photos
05_face_analyzer.ipynb		Unified face analysis
06_face_parsing.ipynb		Semantic face segmentation
07_face_anonymization.ipynb		Privacy-preserving blur
08_gaze_estimation.ipynb		Gaze direction estimation
09_face_segmentation.ipynb		Face segmentation with XSeg
10_face_vector_store.ipynb		FAISS-backed face database
11_head_pose_estimation.ipynb		Head pose estimation (pitch, yaw, roll)
12_face_recognition.ipynb		Standalone face recognition pipeline
13_portrait_matting.ipynb		Portrait matting with MODNet
14_face_attributes.ipynb		Face states (eyes, glasses, sunglasses, mask)
15_face_mesh.ipynb		468 / 478-point dense 3D face mesh

Documentation

Full documentation: https://yakhyo.github.io/uniface/

Execution Providers (ONNX Runtime)

from uniface.detection import RetinaFace

# Force CPU-only inference
detector = RetinaFace(providers=["CPUExecutionProvider"])

See more in the docs: https://yakhyo.github.io/uniface/concepts/execution-providers/

Datasets

See Datasets documentation for download links, benchmarks, and details.

Licensing and Model Usage

UniFace is MIT-licensed, but several pretrained models carry their own licenses. Review: https://yakhyo.github.io/uniface/license-attribution/

Notable examples:

• YOLOv5-Face and YOLOv8-Face weights are GPL-3.0
• FairFace weights are CC BY 4.0
• FaceAttribNet weights are BSD-3-Clause (© Qualcomm Technologies, Inc.)
• BlazeFace and Face Mesh weights are Apache-2.0 (© Google, from MediaPipe)

If you plan commercial use, verify model license compatibility.

References

*SCRFD and ArcFace models are from InsightFace.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md.

Support

If you find this project useful, consider giving it a ⭐ on GitHub — it helps others discover it!

Questions or feedback:

• Discord: https://discord.gg/wdzrjr7R5j
• GitHub Issues: https://github.com/yakhyo/uniface/issues
• DeepWiki Q&A: https://deepwiki.com/yakhyo/uniface

License

This project is licensed under the MIT License.

Disclaimer: This project is not affiliated with or related to Uniface by Rocket Software.