{"id":6938,"library":"uniface","title":"UniFace: All-in-One Face Analysis Library","description":"UniFace is a lightweight, production-ready Python library built on ONNX Runtime for comprehensive face analysis. It provides high-performance capabilities for face detection, recognition, tracking, 106-point landmark detection, face parsing, gaze estimation, age, and gender detection, with hardware acceleration across various platforms. The library is actively maintained, with its current version being 3.5.0, and receives regular updates adding new features and models.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/yakhyo/uniface","tags":["computer-vision","face-detection","face-recognition","face-tracking","facial-landmarks","face-parsing","gaze-estimation","age-detection","gender-detection","deep-learning","onnx","machine-learning"],"install":[{"cmd":"pip install uniface","lang":"bash","label":"Standard Install"},{"cmd":"pip install uniface[gpu]","lang":"bash","label":"Install with CUDA support"}],"dependencies":[{"reason":"Core numerical operations for image and data handling.","package":"numpy","optional":false},{"reason":"Image loading and processing (e.g., `cv2.imread`).","package":"opencv-python","optional":false},{"reason":"Primary inference backend for ONNX models.","package":"onnxruntime","optional":false},{"reason":"Image processing utilities.","package":"scikit-image","optional":false},{"reason":"Enables CUDA acceleration for NVIDIA GPUs.","package":"onnxruntime-gpu","optional":true}],"imports":[{"symbol":"RetinaFace","correct":"from uniface.detection import RetinaFace"},{"symbol":"FaceAnalyzer","correct":"from uniface import FaceAnalyzer"},{"symbol":"ArcFace","correct":"from uniface.recognition import ArcFace"}],"quickstart":{"code":"import cv2\nimport numpy as np\nfrom uniface.detection import RetinaFace\n\n# Create a dummy image for demonstration\n# In a real scenario, replace this with cv2.imread('your_image.jpg')\nimage = np.zeros((480, 640, 3), dtype=np.uint8)\ncv2.putText(image, \"Hello UniFace!\", (100, 240), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)\n\n# Initialize the face detector (models download on first use)\ndetector = RetinaFace(confidence_threshold=0.5, nms_threshold=0.4)\n\n# Detect faces in the image\nfaces = detector.detect(image)\n\nif faces:\n    print(f\"Found {len(faces)} face(s).\")\n    for i, face in enumerate(faces, start=1):\n        print(f\"[Face {i}] Confidence: {face.confidence:.3f}, Bounding Box: {face.bbox}\")\n        # Optionally, you can draw bounding boxes or process further\n        # Example: draw a rectangle around the first face\n        if i == 1:\n            x, y, w, h = int(face.bbox.x), int(face.bbox.y), int(face.bbox.width), int(face.bbox.height)\n            cv2.rectangle(image, (x, y), (x + w, y + h), (0, 255, 0), 2)\nelse:\n    print(\"No faces detected.\")\n\n# You can also use FaceAnalyzer for an all-in-one approach:\n# from uniface import FaceAnalyzer\n# analyzer = FaceAnalyzer()\n# analyzed_faces = analyzer.analyze(image)\n# for face in analyzed_faces:\n#     print(face.bbox, face.embedding.shape if face.embedding is not None else None)","lang":"python","description":"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')`."},"warnings":[{"fix":"Review the official documentation and migration guides for UniFace v3.0.0 to understand the new API structure and update your code accordingly.","message":"UniFace 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.","severity":"breaking","affected_versions":">=2.0.0, <3.0.0"},{"fix":"Ensure 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adhere 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.","message":"There 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.","severity":"gotcha","affected_versions":"All versions, specifically v3.1.1, v3.3.0+"},{"fix":"Consult the UniFace documentation or the source repositories of specific models if you are redistributing applications or models to ensure compliance with all applicable licenses.","message":"UniFace 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `scikit-image` is updated to version `0.26.0` or higher to maintain compatibility and stability.","message":"In 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.","severity":"deprecated","affected_versions":">=3.1.1"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}