DeepFace

Warnings

• breaking In `v0.0.97`, return types for facial landmarks were changed to raw Python types. Code that previously relied on specific object structures for landmark data might require updates to parse the new raw types.
  Fix: Review and update code that processes facial landmark return values to handle raw Python data types instead of previous object structures.
• breaking In `v0.0.96`, the internal reference `training.Model` was replaced with `Model` within the ArcFace model. Users who had custom code directly importing or referencing `training.Model` from DeepFace's internal modules for ArcFace might experience import errors or unexpected behavior.
  Fix: Adjust any direct imports or references from `training.Model` to `Model` if interacting with ArcFace's internal model structure.
• gotcha DeepFace automatically downloads several large pre-trained deep learning models on the first execution of certain functions (e.g., `verify`, `analyze`). This process requires an active internet connection and can lead to a significant delay during the initial run.
  Fix: Ensure an internet connection is available during the first execution. Consider pre-downloading models in deployment environments or during application setup if offline operation is critical.
• gotcha Accuracy of face recognition and analysis can degrade significantly with poor image quality, sub-optimal lighting conditions, occlusions (e.g., masks, sunglasses), or non-frontal face angles. Performance claims are often based on ideal, high-quality inputs.
  Fix: Provide high-quality, well-lit, frontal images whenever possible. Implement pre-processing steps to improve image quality or reject unsuitable inputs if strict accuracy is required.
• gotcha For advanced features like storing and searching face embeddings in vector databases (e.g., PgVector, Pinecone, MongoDB, Weaviate), the corresponding database client packages must be installed separately. `pip install deepface` alone does not include these optional dependencies.
  Fix: Install the specific database client package(s) for the chosen backend (e.g., `pip install pgvector`) in addition to `deepface` if you plan to use database integration for the `find` function.
• gotcha Starting from `v0.0.92`, the `find` function's `refresh_database` argument defaults to `True`. If your application's logic or performance relied on the `find` function *not* automatically refreshing its internal database by default, this change could introduce unexpected re-indexing times.
  Fix: If automatic database refreshing is not desired, explicitly set `refresh_database=False` when calling the `DeepFace.find()` function.
• gotcha Age prediction accuracy can be variable, particularly for older individuals where it may underestimate age. Performance can also be highly dependent on the quality and type of input image, performing best with clear, head-on shots.
  Fix: Be aware of these limitations when relying on age prediction. Consider using age ranges rather than exact age, and optimize for clear, frontal images where possible.

Install

• pip install deepface Install stable release

Imports

• DeepFace

  from deepface import DeepFace

Quickstart

This quickstart demonstrates the core functionalities of DeepFace: face verification, facial attribute analysis (age, gender, emotion, race), and generating face embeddings. It uses dummy image files for immediate execution, but in a real application, you would provide paths to actual face images. Note that DeepFace will automatically download necessary deep learning models on its first execution, which requires an active internet connection and may take some time.

import os
import cv2
import numpy as np
from deepface import DeepFace

# Create dummy image files for demonstration
# In a real scenario, these would be actual image paths
img1_path = "img1.jpg"
img2_path = "img2.jpg"
person_img_path = "person.jpg"

# Generate dummy images (replace with actual image files for real usage)
if not os.path.exists(img1_path):
    cv2.imwrite(img1_path, np.zeros((224, 224, 3), dtype=np.uint8) + 100)
if not os.path.exists(img2_path):
    cv2.imwrite(img2_path, np.zeros((224, 224, 3), dtype=np.uint8) + 150)
if not os.path.exists(person_img_path):
    cv2.imwrite(person_img_path, np.zeros((224, 224, 3), dtype=np.uint8) + 200)

try:
    # Verify two faces
    result_verify = DeepFace.verify(img1_path, img2_path)
    print("Face Verification Result:", result_verify)

    # Analyze facial attributes
    analysis_result = DeepFace.analyze(person_img_path, actions=['age', 'gender', 'emotion', 'race'])
    print("\nFacial Analysis Result:", analysis_result)

    # Generate a face embedding (representation)
    embedding = DeepFace.represent(img1_path)
    print("\nFace Embedding (first 5 elements of first face):", embedding[0]['embedding'][:5])

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you have valid image files at the specified paths.")
    print("Also, DeepFace downloads models on first run, requiring an internet connection.")

# Clean up dummy images (optional)
# os.remove(img1_path)
# os.remove(img2_path)
# os.remove(person_img_path)