{"id":7672,"library":"retina-face","title":"RetinaFace Deep Face Detection","description":"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.","status":"active","version":"0.0.17","language":"en","source_language":"en","source_url":"https://github.com/serengil/retinaface","tags":["face-detection","facial-landmarks","tensorflow","computer-vision","deep-learning"],"install":[{"cmd":"pip install retina-face","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge retina-face","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Core deep learning framework for the model.","package":"tensorflow","optional":false},{"reason":"Commonly used for image loading, processing, and visualization with RetinaFace examples.","package":"opencv-python","optional":true}],"imports":[{"symbol":"RetinaFace","correct":"from retinaface import RetinaFace"}],"quickstart":{"code":"import cv2\nimport os\nfrom retinaface import RetinaFace\n\n# Create a dummy image for demonstration if it doesn't exist\nimage_path = \"test_image.jpg\"\nif not os.path.exists(image_path):\n    # Create a blank white image\n    dummy_image = 255 * (1 + 0 * range(100)).reshape(100, 100, 1) # White image\n    dummy_image = cv2.cvtColor(dummy_image, cv2.COLOR_GRAY2BGR)\n    cv2.imwrite(image_path, dummy_image)\n    print(f\"Created a dummy image at {image_path}\")\n\ntry:\n    # Detect faces in an image\n    # The detect_faces function can accept an image path or a NumPy array.\n    faces = RetinaFace.detect_faces(image_path)\n\n    if isinstance(faces, dict):\n        for face_name, face_data in faces.items():\n            print(f\"--- {face_name} ---\")\n            print(f\"  Score: {face_data['score']}\")\n            print(f\"  Facial Area: {face_data['facial_area']}\")\n            print(f\"  Landmarks: {face_data['landmarks']}\")\n    elif faces is None:\n        print(f\"No faces detected in {image_path}\")\n    else:\n        print(\"Unexpected output format from RetinaFace.detect_faces\")\n\n    # Optional: Draw detections on the image and display (requires opencv-python-headless or opencv-python)\n    # img = cv2.imread(image_path)\n    # if img is not None:\n    #     result_img = RetinaFace.draw_landmarks(img, faces)\n    #     cv2.imshow(\"Detected Faces\", result_img)\n    #     cv2.waitKey(0)\n    #     cv2.destroyAllWindows()\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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)."},"warnings":[{"fix":"Upgrade to `retina-face>=0.0.16` for TensorFlow 2.16+ environments: `pip install --upgrade retina-face`.","message":"TensorFlow 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]","severity":"breaking","affected_versions":"<0.0.16"},{"fix":"Ensure your TensorFlow version is compatible with the `retina-face` version, or upgrade `retina-face` to the latest version which handles this internally.","message":"In `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]","severity":"breaking","affected_versions":"0.0.15"},{"fix":"Be aware of potential minor behavioral changes in face detection and alignment results if migrating from versions older than 0.0.15.","message":"From 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]","severity":"gotcha","affected_versions":"<0.0.15"},{"fix":"Ensure input images are well-formed and review any new 'invalid coordinate' errors; these are likely surfacing real issues that were previously ignored.","message":"Version 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]","severity":"gotcha","affected_versions":"<0.0.17"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed in your active environment: `pip install retina-face`.","cause":"The `retina-face` package is not installed or installed in a different Python environment.","error":"ModuleNotFoundError: No module named 'retinaface'"},{"fix":"Upgrade `retina-face` to the latest version (`pip install --upgrade retina-face`) or ensure your TensorFlow version is compatible (e.g., TensorFlow 2.16+ with RetinaFace 0.0.16+).","cause":"An older version of TensorFlow is being used with a `retina-face` version (e.g., v0.0.15) that expected a lowercase 'valid' for padding due to a TensorFlow API change. [cite: v0.0.15 release]","error":"tensorflow.python.framework.errors_impl.InvalidArgumentError: Invalid padding value 'VALID'. Must be 'SAME' or 'VALID'."},{"fix":"Verify the image file path is correct and the file exists. Use an absolute path or ensure the image is in the current working directory.","cause":"The image file specified in `RetinaFace.detect_faces()` does not exist at the given path.","error":"ValueError: Path not found: [image_path]"},{"fix":"Check the image path. Ensure `opencv-python` (or `opencv-python-headless`) is correctly installed and that the image file is valid and readable.","cause":"OpenCV (cv2.imread) failed to load the image, returning `None`. This can happen if the image path is incorrect, the image is corrupted, or required image codecs are missing.","error":"AttributeError: 'NoneType' object has no attribute 'shape' (often when reading image with OpenCV)"}]}