deepface

DeepFace is a lightweight face recognition and facial attribute analysis (age, gender, emotion and race) framework for python. It is a hybrid face recognition framework wrapping state-of-the-art models: VGG-Face, FaceNet, OpenFace, DeepFace, DeepID, ArcFace, Dlib, SFace, GhostFaceNet, Buffalo_L.

A modern face recognition pipeline consists of 5 common stages: detect, align, normalize, represent and verify. While DeepFace handles all these common stages in the background, you don’t need to acquire in-depth knowledge about all the processes behind it. You can just call its verification, find or analysis function with a single line of code.

Experiments show that human beings have 97.53% accuracy on facial recognition tasks whereas those models already reached and passed that accuracy level.

Installation

The easiest way to install deepface is to download it from PyPI. It's going to install the library itself and its prerequisites as well.

$ pip install deepface

Alternatively, you can also install deepface from its source code. Source code may have new features not published in pip release yet.

$ git clone https://github.com/serengil/deepface.git
$ cd deepface
$ pip install -e .

Once you installed the library, then you will be able to import it and use its functionalities.

from deepface import DeepFace

💡 Prefer not to install or manage infrastructure? You can use a managed API via deepface.dev.

Face Verification - Demo

This function determines whether two facial images belong to the same person or to different individuals. The function returns a dictionary, where the key of interest is verified: True indicates the images are of the same person, while False means they are of different people.

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

Face recognition - Tutorial, Demo

Face recognition requires applying face verification many times. DeepFace provides an out-of-the-box find function that searches for the identity of an input image within a specified database path.

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

Here, the find function relies on a directory-based face datastore and stores embeddings on disk. Alternatively, DeepFace provides a database-backed search functionality where embeddings are explicitly registered and queried with approximate nearest neighbor support. Currently, postgres, mongo, neo4j, pgvector, pinecone and weaviate are supported as backend databases.

# register an image into the database
DeepFace.register(img = "img1.jpg")

# perform exact search
dfs: List[pd.DataFrame] = DeepFace.search(img = "target.jpg")

# perform approximate nearest neighbor search
dfs: List[pd.DataFrame] = DeepFace.search(img = "target.jpg", search_method = "ann")

Facial Attribute Analysis - Demo

DeepFace also comes with a strong facial attribute analysis module including age, gender, facial expression (including angry, fear, neutral, sad, disgust, happy and surprise) and race (including asian, white, middle eastern, indian, latino and black) predictions.

objs: List[dict] = DeepFace.analyze(
  img_path = "img4.jpg", actions = ['age', 'gender', 'race', 'emotion']
)

Age model got ± 4.65 MAE; gender model got 97.44% accuracy, 96.29% precision and 95.05% recall as mentioned in its tutorial.

Real Time Analysis - Demo, React Demo part-i, React Demo part-ii

You can run deepface for real time videos as well. Stream function will access your webcam and apply both face recognition and facial attribute analysis. The function starts to analyze a frame if it can focus a face sequentially 5 frames. Then, it shows results 5 seconds.

DeepFace.stream(db_path = "C:/database")

Even though face recognition is based on one-shot learning, you can use multiple face pictures of a person as well. You should rearrange your directory structure as illustrated below.

user
├── database
│   ├── Alice
│   │   ├── Alice1.jpg
│   │   ├── Alice2.jpg
│   ├── Bob1.jpg

Here, you can also find some real time demos for various models:

Task	Model	Demo
Facial Recognition	DeepFace	Video
Facial Recognition	FaceNet	Video
Facial Recognition	VGG-Face	Video
Facial Recognition	OpenFace	Video
Age & Gender	Default	Video
Race & Ethnicity	Default	Video
Emotion	Default	Video
Celebrity Look-Alike	Default	Video

If you intend to perform face verification or analysis tasks directly from your browser, deepface-react-ui is a separate repository built using ReactJS depending on deepface api.

Embeddings - Tutorial, Demo

Face recognition models basically represent facial images as multi-dimensional vectors. Sometimes, you need those embedding vectors directly. DeepFace comes with a dedicated representation function.

embedding_objs: List[dict] = DeepFace.represent(img_path = "img.jpg")