Registry / ai-ml / retina-face

retina-face

JSON →
library0.0.18pypypi✓ verified 82d ago

RetinaFace is a deep learning-based, cutting-edge facial detector for Python, providing high-precision face localization and facial landmarks. It's built on a TensorFlow re-implementation of the original RetinaFace model from the InsightFace project. The library simplifies the underlying C dependencies and handles pre-trained weight downloads automatically, making it pip-compatible and easy to use. The current version is 0.0.17, with a moderately active release cadence addressing compatibility and performance improvements.

pip install retina-face
INSTALL
IMPORT
SIG · RETINA-FACE
R
retina-face
ai-mlpythonv0.0.18
Install
34.9s avg
Import
Disk
2355MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.18 · 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
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 34.9s · import 0.000s · 2355.2MB
2355MB installed
● package 2355MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RetinaFace
import retinaface
from retinaface import RetinaFace

This quickstart demonstrates how to import `RetinaFace` and use its `detect_faces` function to find faces and facial landmarks in an image. It includes a placeholder to create a dummy image if one isn't present, making the code immediately runnable. The output includes confidence scores, bounding box coordinates (`facial_area`), and five key facial landmarks (eyes, nose, mouth corners).

import cv2 import os from retinaface import RetinaFace # Create a dummy image for demonstration if it doesn't exist image_path = "test_image.jpg" if not os.path.exists(image_path): # Create a blank white image dummy_image = 255 * (1 + 0 * range(100)).reshape(100, 100, 1) # White image dummy_image = cv2.cvtColor(dummy_image, cv2.COLOR_GRAY2BGR) cv2.imwrite(image_path, dummy_image) print(f"Created a dummy image at {image_path}") try: # Detect faces in an image # The detect_faces function can accept an image path or a NumPy array. faces = RetinaFace.detect_faces(image_path) if isinstance(faces, dict): for face_name, face_data in faces.items(): print(f"--- {face_name} ---") print(f" Score: {face_data['score']}") print(f" Facial Area: {face_data['facial_area']}") print(f" Landmarks: {face_data['landmarks']}") elif faces is None: print(f"No faces detected in {image_path}") else: print("Unexpected output format from RetinaFace.detect_faces") # Optional: Draw detections on the image and display (requires opencv-python-headless or opencv-python) # img = cv2.imread(image_path) # if img is not None: # result_img = RetinaFace.draw_landmarks(img, faces) # cv2.imshow("Detected Faces", result_img) # cv2.waitKey(0) # cv2.destroyAllWindows() except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingTensorFlow versions 2.16 and later require RetinaFace v0.0.16 or higher for full compatibility. Older versions might encounter issues due to TensorFlow API changes. [cite: v0.0.16 release]
fix
Upgrade to `retina-face>=0.0.16` for TensorFlow 2.16+ environments: `pip install --upgrade retina-face`.
affects: <0.0.16
breakingIn `retina-face` v0.0.15, TensorFlow's padding argument changed from 'VALID' to 'valid' (lowercase), causing exceptions in older TensorFlow versions if 'VALID' was used. The library was updated to use 'valid'. [cite: v0.0.15 release]
fix
Ensure your TensorFlow version is compatible with the `retina-face` version, or upgrade `retina-face` to the latest version which handles this internally.
affects: 0.0.15
gotchaFrom v0.0.15 onwards, the internal processing order was changed to align faces first, then detect, which can lead to different (often improved) results, especially by reducing 'meaningless black pixels'. [cite: v0.0.15 release]
fix
Be aware of potential minor behavioral changes in face detection and alignment results if migrating from versions older than 0.0.15.
affects: <0.0.15
gotchaVersion 0.0.17 introduced validation for projected coordinates against the base image size to prevent failures from invalid coordinates. While a fix, it might expose underlying issues with input images or detection in extreme cases that were previously silently handled. [cite: v0.0.17 release]
fix
Ensure input images are well-formed and review any new 'invalid coordinate' errors; these are likely surfacing real issues that were previously ignored.
affects: <0.0.17
Upgrade
Version history
0.0.18latest on PyPI · released Jun 1, 2026
Audit
Dependencies
tensorflowrequiredCore deep learning framework for the model.
opencv-pythonoptionalCommonly used for image loading, processing, and visualization with RetinaFace examples.
Agent activity
17 hits · last 30 days
node
12
OpenAI (training)
1
Resources
retina-face — pip install retina-face · libregistry