{"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":"python","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":[{"wrong":"from retinaface import RetinaFace","symbol":"RetinaFace","correct":"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,"search_vec":"'0.0.17':74 'activ':78 'address':81 'automat':60 'base':11 'built':30 'c':51 'cadenc':80 'compat':65,82 'comput':94 'computer-vis':93 'current':71 'cut':13 'cutting-edg':12 'deep':2,8,97 'deep-learn':96 'depend':52 'detect':4,88 'detector':16 'download':59 'easi':67 'edg':14 'face':3,23,87 'face-detect':86 'facial':15,26,90 'facial-landmark':89 'handl':54 'high':21 'high-precis':20 'implement':36 'improv':85 'insightfac':44 'landmark':27,91 'learn':10,98 'learning-bas':9 'librari':47 'local':24 'make':61 'model':41 'moder':77 'origin':39 'perform':84 'pip':64 'pip-compat':63 'pre':56 'pre-train':55 'precis':22 'project':45 'provid':19 'python':18 're':35 're-implement':34 'releas':79 'retinafac':1,5,40 'simplifi':48 'tensorflow':33,92 'train':57 'under':50 'use':69 'version':72 'vision':95 'weight':58","created_at":"2026-04-16T14:08:26.144957+00:00","updated_at":"2026-04-16T14:08:26.144957+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.18","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/serengil/retinaface","docs":null,"changelog":null,"pypi":"https://pypi.org/project/retina-face/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":null}}