How to Install and Use RetinaFace in Python

Setting up RetinaFace in Python is straightforward with the pip-installable package. This guide covers installation, loading a pre-trained model, running detection on an image, and interpreting the results for use in your own pipeline.

Prerequisites

Python 3.7 or higher
pip (comes with Python)
NumPy, OpenCV (installed automatically as dependencies)
Optional: NVIDIA GPU with CUDA 11.x for GPU acceleration
Optional: PyTorch 1.9+ if using PyTorch-based models

Installation

Install the RetinaFace package from PyPI using a single pip command. It is recommended to use a virtual environment to keep your project dependencies isolated.

python -m venv venv
source venv/bin/activate
pip install retinaface

Basic Usage

from retinaface import RetinaFace

result = RetinaFace.detect_faces("path/to/image.jpg")

for face_key, face_data in result.items():
    print(face_data['score'])
    print(face_data['facial_area'])
    print(face_data['landmarks'])

Extracting Aligned Face Crops

from retinaface import RetinaFace

faces = RetinaFace.extract_faces(img_path="group_photo.jpg", align=True)

for i, face in enumerate(faces):
    import cv2
    cv2.imwrite(f"face_{i}.jpg", face)

Common Configuration Options

threshold: Confidence cutoff (0.0 to 1.0, default 0.9)
model: Backend model to use (mxnet or pytorch variant)
align: Whether to return aligned crops (True or False)

Troubleshooting Common Issues

Model download fails: Ensure internet connectivity on first run
ImportError for cv2: Run pip install opencv-python
Slow inference: Ensure CUDA is available if GPU is expected
No faces detected: Check image orientation and try lowering the threshold

Conclusion

Installing and using RetinaFace in Python requires minimal setup. The pip package handles model management automatically, and the API is clean enough to integrate into a working face detection pipeline in under 10 lines of code.

How to Install and Use RetinaFace in Python