serengil/deepface

DeepFace is a modular facial analysis library that provides face recognition, verification, detection, and demographic attribute analysis. It supports both TensorFlow and PyTorch backends and offers a REST API with optional authentication and pre-loaded models for low-latency inference. The system also includes pluggable database backends for storing and searching face embeddings, along with tools for benchmarking and experimental boosting algorithms.

7 changes.

The project underwent a major architectural refactoring to support PyTorch alongside TensorFlow, introducing a modular structure with abstract interfaces for models and utilities. Legacy Keras-based models and monolithic code were removed in favor of a cleaner, extensible design with split dependency management and enhanced API flexibility.

11 changes.

This period focused on modernizing the DeepFace API with modular architecture, bearer token authentication, and pre-loaded models to reduce latency. It significantly expanded backend support by introducing PyTorch implementations for demography and anti-spoofing models, refactoring face detection and recognition modules for better modularity, and adding pluggable database backends for embedding storage.

7 changes.

The project introduced PyTorch backend support for facial recognition models, enabling users to switch from TensorFlow while maintaining compatibility. Concurrently, the architecture was modernized with dependency injection and environment-driven configuration, alongside Docker Compose setups for local vector search development. Comprehensive testing and experimental notebooks for confidence calibration and boosting algorithms were also added to enhance reliability and analytical capabilities.

The project now includes a Docker Compose setup in the \docker/\ directory to facilitate local development and testing of vector search capabilities. This configuration defines services for a standard PostgreSQL database, a pgvector-enabled PostgreSQL instance (with the vector extension initialized), and a Weaviate vector database. It also provides the necessary SQL initialization scripts to create the \embeddings\ and \embeddings\_index\ tables required for storing face embeddings and their associated metadata.

docker · high confidence

New Jupyter notebooks have been added to the boosted directory to perform face recognition experiments using the LFW dataset. The \Perform-Boosting-Experiments-LightGBM.ipynb\ notebook integrates the LightGBM library to apply boosting algorithms to face embeddings extracted by DeepFace models (Facenet, VGG-Face, ArcFace, etc.). Similarly, \Perform-Boosting-Experiments-XGBoost.ipynb\ introduces XGBoost for the same purpose. Additionally, a trained LightGBM model file (\boosted\_lightface\_7.txt\) has been added to the models directory, representing a specific boosted configuration using these face recognition features.

boosted · high confidence

A new Jupyter notebook has been added to the experiments directory that demonstrates how to convert face verification distances into probabilistic confidence estimates. The notebook builds a logistic regression model to map distance metrics (such as cosine or euclidean) to a probability score, providing a softer, more informative measure of certainty compared to the standard hard classification threshold.

experiments · high confidence

This release introduces PyTorch as a supported backend engine alongside the existing TensorFlow, allowing users to install the library via \pip install deepface\[pytorch\]\ or \pip install deepface\[tensorflow\]\ to avoid pulling in unnecessary dependencies. The package version is updated to 0.0.101, and the minimum Python requirement is raised to 3.7. Additionally, the framework now includes a command-line interface accessible via the \deepface\ console script, and the Dockerfile has been updated to support the new entrypoint and dependency structure.

(repo-wide) · high confidence

Added \Perform-Experiments.ipynb\ and \Evaluate-Results.ipynb\ to the \benchmarks\ directory, enabling users to reproduce accuracy experiments on the LFW dataset using DeepFace v0.0.90. These notebooks allow users to run experiments across various configurations of facial recognition models (e.g., Facenet512, VGG-Face), detectors (e.g., retinaface, mtcnn), and distance metrics, and then evaluate the results. A new \README.md\ documents these benchmarks, presenting performance matrices and ROC curves for different model and detector combinations.

benchmarks · high confidence

Added three new shell scripts to streamline the project's operational workflows. The \dockerize.sh\ script automates building the Docker image and running the container, mapping port 5005 and optionally loading environment variables from \deepface/api/.env\. The \service.sh\ script provides a command to start the API using Gunicorn for production-like execution. The \push-release.sh\ script automates the creation of PyPI-compatible distribution packages and uploads them to PyPI.

scripts · high confidence

Users can now store and search face embeddings using a variety of external databases. This change introduces a pluggable architecture with clients for PostgreSQL, MongoDB, Weaviate, Neo4j, Pinecone, Milvus, and Qdrant, registered in the new \deepface/modules/database/inventory.py\. The \Database\ abstract base class in \types.py\ defines the interface for these clients, allowing the library to offload embedding storage and vector search to specialized systems rather than relying solely on local file-based storage.

deepface/modules · high confidence

The face anti-spoofing detection capability now supports PyTorch as an alternative to the existing TensorFlow backend. This change introduces a new \pytorch\ subdirectory containing PyTorch-specific implementations of the FasNet model and its backbone layers, allowing users to run spoofing analysis using PyTorch tensors and devices (CPU/GPU) instead of being restricted to TensorFlow/Keras.

deepface/models/spoofing · high confidence

The Age, Gender, Emotion, and Race models in the demography module now support the PyTorch backend in addition to the existing TensorFlow/Keras implementation. This change introduces a new \pytorch\ subdirectory containing PyTorch-specific model definitions (e.g., \ApparentAgeClient\, \EmotionClient\) and a shared base class \TorchDemography\ that handles device placement and tensor conversion. Users can now run facial attribute analysis using PyTorch, which may offer performance benefits or compatibility with PyTorch-centric workflows, while the TensorFlow implementations remain available.

deepface/models/demography · high confidence

Users can now run facial recognition models using the PyTorch backend instead of TensorFlow. This change adds PyTorch implementations for ArcFace, DeepID, FaceNet (128d and 512d), Facebook DeepFace, GhostFaceNet, OpenFace, and VGG-Face, along with a shared base class and weight-loading utilities. The PyTorch models replicate the behavior of the existing TensorFlow backends, including input shapes, output embedding dimensions, and batch normalization configurations, allowing users to switch backends while maintaining compatibility with pre-trained weights.

_deepface/models/facial\recognition/pytorch · high confidence

The Facenet, OpenFace, and VGGFace model implementations have been removed from the codebase. These files, which relied on the legacy Keras API (e.g., \Convolution2D\, \Sequential\), are no longer part of the library, indicating a shift away from these specific model architectures or their underlying framework versions.

deepface/basemodels · high confidence

The application now uses a dependency injection container to manage services like authentication, replacing previous ad-hoc initialization. Configuration is centralized in a new Variables class that reads settings from environment variables (such as database type, connection details, and model selections) and validates the database type against a known inventory, ensuring that unsupported database types are rejected at startup.

deepface/api/src/dependencies · high confidence

The library now enforces a structured object-oriented design by introducing abstract base classes (ABCs) for core model types: FacialRecognition, Detector, and Demography. These interfaces standardize how models are implemented and invoked, defining common methods like \forward\ for embeddings and \detect\_faces\ for face localization. The \Detector\ interface also introduces structured data classes (\FacialAreaRegion\, \DetectedFace\) to return consistent metadata such as bounding boxes, confidence scores, and key points (eyes, nose, mouth). This change ensures that all specific model implementations (e.g., VGG-Face, RetinaFace, Emotion) adhere to a unified contract, improving code maintainability and enabling easier integration of new backends or models.

deepface/models · high confidence

The API module has been reorganized into the deepface/api directory to improve testability. Users can now configure the application to load face recognition and detection models at startup via environment variables (DEEPFACE\_FACE\_RECOGNITION\_MODELS, DEEPFACE\_FACE\_DETECTION\_MODELS) to reduce first-request latency, and can enable bearer token authentication by setting DEEPFACE\_AUTH\_TOKEN. Additionally, the API endpoints now expect image parameters named img, img1, and img2 instead of the previous img\_path, img1\_path, and img2\_path.

deepface/api · high confidence

The \deepface/config\ module now provides structured configuration files for confidence score normalization and decision thresholds across supported face recognition models (VGG-Face, Facenet, ArcFace, etc.). Users benefit from empirically derived min-max values and distance thresholds for various metrics (cosine, euclidean, angular), allowing for more accurate and consistent similarity assessments and match decisions without hard-coded constants in the core logic.

deepface/config · high confidence

The DeepFace API has been refactored into a modular structure (core and auth modules) with the introduction of Bearer token authentication, requiring a valid token for all API calls when enabled. This update also adds support for the \max\_faces\ argument in the \/represent\ endpoint, enables anti-spoofing checks across represent, verify, and analyze endpoints, and improves error handling by including detailed exception logs in API responses. The API now supports loading images from both JSON payloads and multipart form data, and the home route displays the current DeepFace version.

deepface/api/src/modules/core · high confidence

The deepface/commons module has been significantly restructured to support both TensorFlow and PyTorch backends. A new backend\_utils.py handles engine selection via the DEEPFACE\_BACKEND\_ENGINE environment variable, while folder\_utils.py introduces a configurable home directory via the DEEPFACE\_HOME environment variable. Image handling is consolidated in image\_utils.py, which now supports loading from URLs, file objects, and base64 strings, and replaces the old functions.py with dedicated modules for logging (logger.py), weight management (weight\_utils.py), and package validation (package\_utils.py). The legacy distance.py and functions.py files have been removed.

deepface/commons · high confidence

The face detection backends in this module have been restructured into individual, modular classes (CenterFace, Dlib, FastMtCnn, MediaPipe, MtCnn, OpenCv, RetinaFace, Ssd, Yolo, YuNet) that implement a common Detector interface. This change introduces environment-variable configuration for detection sensitivity: CenterFace now respects CENTERFACE\_THRESHOLD, MediaPipe respects MEDIAPIPE\_MIN\_DETECTION\_CONFIDENCE and MEDIAPIPE\_MODEL\_SELECTION, and YOLO respects YOLO\_MIN\_DETECTION\_CONFIDENCE. The Yolo backend has been expanded to support additional model variants (yolov11n, yolov11m, yolov11s, yolov11l, yolov12n, yolov12s, yolov12m, yolov12l) alongside existing v8 models, with version checks for the ultralytics library. RetinaFace now explicitly returns nose and mouth landmark coordinates in addition to eyes. OpenCv's eye detection logic has been improved to consistently select the two largest detected eyes to handle ordering inconsistencies. YuNet now automatically resizes large input images to prevent detection failures. FastMtCnn coordinates are now cast to integers for consistency.

_deepface/models/face\detection · high confidence

The facial recognition models in this package have been restructured into separate files (ArcFace, Buffalo\_L, DeepID, Dlib, FaceNet, FbDeepFace, GhostFaceNet, OpenFace, SFace, VGGFace), each implementing the FacialRecognition interface. This change introduces support for batch processing in several models (Buffalo\_L, Dlib, SFace, VGGFace) and adds the new Buffalo\_L model (InsightFace-based) and ArcFace model. The refactoring also standardizes weight downloading through a common utility and improves error handling for missing dependencies and invalid inputs.

_deepface/models/facial\recognition · high confidence

The library has been refactored from a single monolithic module into a modular architecture with separate components for modeling, representation, verification, recognition, demography, detection, streaming, preprocessing, and datastore. This change introduces official support for the PyTorch backend alongside TensorFlow, allowing users to choose their preferred engine. The public API functions (verify, represent, find, analyze, etc.) now accept IO\[bytes\] objects and pre-calculated embeddings, and the verify function now returns a confidence score in addition to distance and threshold. A deprecation warning has been added to inform users that future major releases will require explicit backend installation (e.g., deepface\[tensorflow\] or deepface\[pytorch\]).

deepface · high confidence

The DeepFace API now loads specified face recognition and detection models during application initialization rather than waiting for the first request. This change, driven by the new \load\_models\_on\_startup\ function in \app.py\, significantly reduces latency for the initial user request by ensuring models are ready in memory when the server starts.

deepface/api/src · high confidence

Added integration tests for PostgreSQL database operations and unit tests for API and analysis features; Removal of legacy unit test script.

The project's dependency configuration has been reorganized from a single file into a modular structure to support different installation profiles. A new \requirements.txt\ (and \requirements\_base.txt\) defines the core runtime dependencies, including \Flask\, \gunicorn\, \opencv-python\, and \lightphe\. Separate files now handle specific needs: \requirements\_tf.txt\ and \requirements\_pytorch.txt\ isolate TensorFlow and PyTorch backends respectively, while \requirements\_additional.txt\ groups optional libraries like \mediapipe\, \dlib\, and \ultralytics\. A new \requirements-dev.txt\ file explicitly lists \pytest\ for development environments.

(dependencies) · high confidence

An empty \_\init\\_.py file was added to the deepface/api/src/modules directory, converting it into a Python package.

deepface/api/src/modules · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 56.

• Code Health 91
• Architecture 92
• Maturity 66
• Readiness 31
• Security 88

• 300 commits — 290 feature/other, 10 fixes

• (root) — 144 commits
• (repo) — 43 commits
• deepface/modules — 40 commits
• deepface/models — 34 commits
• deepface/DeepFace.py — 8 commits
• deepface/api — 4 commits
• tests/test_represent.py — 4 commits
• tests/test_api.py — 3 commits
• tests/unit — 3 commits
• .github/workflows — 2 commits
• icon/face-verification-credit.jpg — 2 commits
• .codeboarding/External_Integration_Layer.md — 1 commit
• .github/pull_request_template.md — 1 commit
• deepface/init.py — 1 commit
• deepface/config — 1 commit
• icon/deepface-realtime.jpg — 1 commit
• icon/encrypt-embeddings.jpg — 1 commit
• icon/facenet-pca.png — 1 commit
• icon/github_sponsor_button.png — 1 commit
• icon/verify-credit.jpg — 1 commit

• fix: Fix AttributeError in streaming
• fix: Fix FastMtCnn detection error
• fix: Fix double normalization of pre-extracted faces (#1613) (#1621)
• fix: Merge pull request #1463 from CatBraaain/fix/typo-in-pytorch-error-message
• fix: Merge pull request #1475 from catherinetcai/streaming-bugfix
• fix: chore: ⏪️ Revert flask and werkzeug dependency changes
• fix: fix 'lines too long' lint issue
• fix: replace training.Model with Model | [BUG]: Getting AttributeError: 'KerasHistory' object has no attribute 'layer' when calling DeepFace.represent with detector_backend="retinaface"
• fix: spoofing module class bug sorted (#1581)
• fix: ⏪ Revert test_invalid_verify
• change: Add Angular Distance to Documentation
• change: Add Hacker News badge to README
• change: Add deepface.dev README updates (#1593)
• change: Add files via upload
• change: Add files via upload
• change: Add files via upload
• change: Add files via upload
• change: Add files via upload
• change: Add files via upload
• change: Add logging to test case.
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

serengil/deepface was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.