Registry / ai-ml / deepface

deepface

JSON →
library0.0.100pypypi✓ verified 27d ago

DeepFace is an open-source Python library for lightweight face recognition and facial attribute analysis (age, gender, emotion, and race). It acts as a hybrid framework, wrapping 11 state-of-the-art models into a single, easy-to-use interface. The library is actively maintained with frequent releases, often on a weekly or bi-weekly basis, and supports Python 3.7+.

pip install deepface
INSTALL
IMPORT
SIG · DEEPFACE
D
deepface
ai-mlpythonv0.0.100
Install
46.0s avg
Import
—
Disk
2519MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.0.100 · 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.10–3.95 runs
build_error
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 46.0s · import 0.000s · 2457.6MB
2519MB installed
● package 2519MB
Code
Verified usage

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

DeepFace
✓ import deepface
✗ from deepface import DeepFace

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)
Debug
Known issues
breakingIn `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.
affects: >=0.0.97
breakingIn `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.
affects: >=0.0.96
gotchaDeepFace 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.
affects: All
gotchaAccuracy 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.
affects: All
gotchaFor 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.
affects: >=0.0.98
gotchaStarting 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.
affects: >=0.0.92
gotchaAge 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.
affects: All
Upgrade
Version history
0.0.100latest on PyPI · released May 9, 2026
Audit
Dependencies
tensorflowrequiredCore deep learning backend for models.
opencv-pythonrequiredEssential for image processing, face detection, and alignment.
numpyrequiredFundamental package for numerical operations.
pandasrequiredData manipulation and analysis, often used for results.
gdownrequiredUsed for downloading pre-trained models from Google Drive.
tqdmrequiredProgress bars for model downloads and processing.
PillowrequiredImage processing utility.
requestsrequiredHTTP client for various internal operations.
FlaskoptionalFor the optional DeepFace API server.
WerkzeugoptionalDependency for Flask, for the optional DeepFace API server.
pgvectoroptionalOptional backend for vector database integration with PostgreSQL for the `find` function.
pinecone-clientoptionalOptional backend for vector database integration with Pinecone for the `find` function.
pymongooptionalOptional backend for vector database integration with MongoDB for the `find` function.
weaviate-clientoptionalOptional backend for vector database integration with Weaviate for the `find` function.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
deepface — pip install deepface · libregistry