Install & Compatibility
Where this runs
tested against v3.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 19.03s
py 3.11
✕ build_error
✓ 15.88s
py 3.12
✕ build_error
✓ 15.09s
py 3.13
✕ build_error
✓ 15.61s
py 3.9
✕ build_error
✕ build_error
828MB installed
● package 828MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RetinaFace
✓ from uniface import RetinaFace
✗ from uniface import RetinaFace
This quickstart demonstrates how to initialize a RetinaFace detector and use it to detect faces in an image. Models are automatically downloaded and cached upon their first use. The example includes creating a dummy image and printing detection results. For real-world use, replace the dummy image with `cv2.imread('your_image.jpg')`.
import cv2
import numpy as np
from uniface.detection import RetinaFace
# Create a dummy image for demonstration
# In a real scenario, replace this with cv2.imread('your_image.jpg')
image = np.zeros((480, 640, 3), dtype=np.uint8)
cv2.putText(image, "Hello UniFace!", (100, 240), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
# Initialize the face detector (models download on first use)
detector = RetinaFace(confidence_threshold=0.5, nms_threshold=0.4)
# Detect faces in the image
faces = detector.detect(image)
if faces:
print(f"Found {len(faces)} face(s).")
for i, face in enumerate(faces, start=1):
print(f"[Face {i}] Confidence: {face.confidence:.3f}, Bounding Box: {face.bbox}")
# Optionally, you can draw bounding boxes or process further
# Example: draw a rectangle around the first face
if i == 1:
x, y, w, h = int(face.bbox.x), int(face.bbox.y), int(face.bbox.width), int(face.bbox.height)
cv2.rectangle(image, (x, y), (x + w, y + h), (0, 255, 0), 2)
else:
print("No faces detected.")
# You can also use FaceAnalyzer for an all-in-one approach:
# from uniface import FaceAnalyzer
# analyzer = FaceAnalyzer()
# analyzed_faces = analyzer.analyze(image)
# for face in analyzed_faces:
# print(face.bbox, face.embedding.shape if face.embedding is not None else None)
Debug
Known issues
breakingUniFace v3.0.0 introduced a redesigned unified API with standardized return types. Code written for versions prior to 3.0.0 may require updates to align with the new API format and data structures.fixReview the official documentation and migration guides for UniFace v3.0.0 to understand the new API structure and update your code accordingly.
affects: >=2.0.0, <3.0.0
gotchaThe library automatically downloads and caches models upon their first use. The default cache location is `~/.uniface/models`. This can be an issue in environments with restricted network access, limited disk space, or specific security policies.fixEnsure network connectivity for initial model downloads. You can programmatically override the cache directory or pre-download models for offline deployments if needed. Check the documentation for `verify_model_weights` and environment variable options.
affects: All versions
gotchaThere have been inconsistent statements regarding Python 3.10 support. While PyPI and `pyproject.toml` for v3.5.0 indicate support for Python `>=3.10,<3.15`, the v3.1.1 changelog noted a drop of Python 3.10 support (setting minimum to 3.11), which was seemingly re-added in v3.3.0. For the latest versions, Python 3.10 is currently listed as supported, but ensure your environment meets the `>=3.10,<3.15` range.fixAdhere to the `requires-python` range specified in the official PyPI metadata (`>=3.10,<3.15`). If you encounter issues with Python 3.10, consider upgrading to Python 3.11 or later within the supported range.
affects: All versions, specifically v3.1.1, v3.3.0+
gotchaUniFace uses various underlying models, some of which may have licenses different from UniFace's MIT License. For example, YOLOv5-Face and YOLOv8-Face weights are GPL-3.0, and FairFace weights are CC BY 4.0. Users should be aware of these individual model licenses for compliance.fixConsult the UniFace documentation or the source repositories of specific models if you are redistributing applications or models to ensure compliance with all applicable licenses.
affects: All versions
deprecatedIn v3.1.1, the minimum required `scikit-image` version was bumped to `>=0.26.0`. Older versions of `scikit-image` may cause compatibility issues or unexpected behavior with UniFace versions 3.1.1 and newer.fixEnsure `scikit-image` is updated to version `0.26.0` or higher to maintain compatibility and stability.
affects: >=3.1.1
Upgrade
Version history
3.7.0latest on PyPI · released May 27, 2026
Audit
Dependencies
numpyrequiredCore numerical operations for image and data handling.
opencv-pythonrequiredImage loading and processing (e.g., `cv2.imread`).
onnxruntimerequiredPrimary inference backend for ONNX models.
scikit-imagerequiredImage processing utilities.
onnxruntime-gpuoptionalEnables CUDA acceleration for NVIDIA GPUs.