DeepFace: one-line face verification on ONNX by default, with a pandas change and an old Docker base to plan around

One-line verify and find calls over ten wrapped recognition models

DeepFace wraps VGG-Face, FaceNet, OpenFace, DeepFace, DeepID, ArcFace, Dlib, SFace, GhostFaceNet and Buffalo_L, and runs the five stages of a face recognition pipeline (detect, align, normalize, represent, verify) behind a single call. Verification compares two images and returns a dictionary whose verified key is True for the same person and False otherwise:

result: dict = DeepFace.verify(img1_path = "img1.jpg", img2_path = "img2.jpg")

Recognition is verification repeated many times. The find function searches for the identity in an input image within a folder, an s3 location or an ftp location:

dfs: List[pd.DataFrame] = DeepFace.find(img_path = "img1.jpg", db_path = "C:/my_db")

The library also does facial attribute analysis for age, gender, emotion and race. The project is MIT licensed, the default branch is master, and the latest push was on 2026-10-31.

ONNX Runtime is the default engine; TensorFlow and PyTorch cost gigabytes

DeepFace is framework agnostic. It runs on ONNX Runtime by default, which keeps the install at a few hundred MB, while TensorFlow or PyTorch add one to several GB. onnxruntime is part of requirements_base.txt, so a plain install is enough:

# runs deepface on onnxruntime by default
$ pip install deepface

# or to run deepface on tensorflow
# $ pip install "deepface[tensorflow]"

# or to run deepface on pytorch
# $ pip install "deepface[pytorch]"

# manage backend deep learning framework if you have many
# export DEEPFACE_BACKEND_ENGINE=onnx  # or tensorflow, pytorch

If more than one framework is present, DEEPFACE_BACKEND_ENGINE decides which one runs. The Makefile uses the same variable to run the unit tests per engine through test-tf, test-pytorch and test-onnx. Installing from a git clone with pip install -e . picks up features that have not reached a PyPI release yet, at the cost of running unreleased code.

find returns pandas DataFrames, and pandas is leaving the base install

The find function is typed to return a list of pandas DataFrames. A comment in setup.py says pandas will not be a base requirement in the future and that pip install "deepface[pandas]" installs it. The consequence is easy to miss: code written today against a plain pip install deepface gets pandas for free, but a later release can drop it, and the first sign will be an import failure or a missing return type inside find. If your application depends on DataFrame results, declare the pandas extra in your own requirements now rather than relying on the transitive install. The same file defines extras for api, cli and grpc, each with its own requirements file, so a minimal install stays minimal and serving features are opt-in.

identify and search move embeddings into one of fifteen databases

For larger galleries, DeepFace can register embeddings in a database instead of computing them on the fly or storing them in local file structures. Supported backends are postgres, mongo, neo4j, pgvector, pinecone, milvus, qdrant, weaviate, sqlite, oracle, mssql, db2, redis, cassandra and mysql. Two database-backed functions mirror the file-based ones. identify is the database-backed alternative to verify for 1:1 identity checks, and search is the alternative to find for 1:N search, with optional approximate nearest neighbor support. Images enter the database through DeepFace.register. Moving to this path changes your operational picture: you now run and back up a database that holds face embeddings, which is personal data in many jurisdictions, and you have to choose whether approximate search is acceptable for your accuracy needs.

The Dockerfile still starts from python:3.8.12-slim

A Docker image is published as serengil/deepface, and the repository's Dockerfile builds from python:3.8.12-slim. It copies the deepface package, every requirements file and entrypoint.sh into /app, and installs from source rather than PyPI, noting that the PyPI release might be out of date. GPU support is not on by default: a commented line says to install tensorflow-gpu if you plan to use a GPU. Face anti-spoofing is also behind a commented line that pins torch==2.1.2. Anyone building this image unchanged gets a Python 3.8 runtime and CPU inference. Teams with a policy on base image age, or who need GPU or anti-spoofing, will have to edit the Dockerfile and rebuild rather than use it as shipped.

The 97.53% human baseline is a claim to check, not a guarantee

The project cites experiments showing that human beings have 97.53% accuracy on facial recognition tasks, and states that the wrapped models have reached and passed that level. The supporting work lives in the benchmarks/ folder, with an experiments/ folder beside it. That figure comes from the project's own experiments on its chosen data, so it says little about your camera angles, lighting or population. Verification depends on a threshold, and the project links a tutorial on fine-tuning it, which signals that the default threshold is a starting point. Attribute predictions for age, gender, emotion and race are model estimates of apparent attributes from an image. Measure error rates on a sample of your own data before using any of these outputs to make decisions about people.

Version 0.0.103 with REST, CLI and gRPC serving as extras

Releases are frequent but the version line has not left 0.0.x: v0.0.101 shipped on 2026-09-16, v0.0.102 on 2026-10-09 and v0.0.103 on 2026-10-20. The version is read from package_info.json at build time. Beyond the Python API, deepface[api] installs what is needed to serve DeepFace as a REST API, deepface[cli] adds command-line use, and deepface[grpc] serves it over gRPC. The Makefile has a grpc target that regenerates Python stubs from deepface/api/proto/deepface.proto and a grpc-server target that starts deepface/api/src/grpc_server.py. Quality checks run through make lint, which requires a pylint score of 10 and passes mypy. For those who would rather not run infrastructure at all, a managed API is offered at deepface.dev.

Editorial conclusion

DeepFace suits Python developers who want face verification, folder or database search, and attribute analysis without assembling detection, alignment and embedding models themselves, and who are happy on ONNX Runtime by default. It is a poorer fit if you need a version number that signals API stability, since releases are still 0.0.x, or if you plan to ship the stock Dockerfile on its Python 3.8.12 base. Before relying on it, install the pandas extra explicitly if your code uses find results, and check the benchmarks/ folder against your own images.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. serengil/deepface on GitHub