Skip to content
Get packs

Guide · Open source

How to use deepface: install, verify and find faces in Python

Updated · written with AI from the project's own documentation and checked against our catalogue data

DeepFace is an open-source Python library for face recognition and facial attribute analysis. It can tell whether two photos show the same person, search a folder or database for a matching face, and estimate age, gender, emotion and race. This guide walks through installing it and running its main functions with a few lines of code.

deepfaceserengil/deepface · ★ 23.6k · MIT

Quick start

  1. 1Install the library. Run pip install deepface to get the default ONNX Runtime backend. Choose the TensorFlow or PyTorch extra only if you need it.
  2. 2Import DeepFace. Add from deepface import DeepFace at the top of your Python script.
  3. 3Verify two faces. Call DeepFace.verify with two image paths and read the verified key in the returned dictionary.
  4. 4Search a folder. Call DeepFace.find with an image path and a db_path folder to find matching faces.
  5. 5Move to a database if needed. Use DeepFace.register to store embeddings, then identify or search against a supported database backend.

Install deepface with pip

The easiest way to install deepface is from PyPI with pip. The install also brings in the library's prerequisites. By default deepface runs on ONNX Runtime, which keeps the install lightweight at a few hundred MB.

If you prefer TensorFlow or PyTorch, install the matching extra. The README notes that these typically add one to several GB, so only choose them if you want that framework.

  • Default (ONNX Runtime): pip install deepface
  • TensorFlow backend: pip install "deepface[tensorflow]"
  • PyTorch backend: pip install "deepface[pytorch]"
  • To manage the backend, set DEEPFACE_BACKEND_ENGINE to onnx, tensorflow or pytorch
$ pip install deepface

Install from source instead of PyPI

You can also install from the source code. The README says the source may include features not yet published in a pip release. Run the editable install from inside the cloned folder.

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

Verify whether two photos show the same person

DeepFace.verify compares two facial images. It returns a dictionary, and the key you usually need is verified. True means the images show the same person, and False means they show different people.

Import the library once, then pass the two image paths.

  • Key result: verified (True or False)
from deepface import DeepFace result: dict = DeepFace.verify(img1_path = "img1.jpg", img2_path = "img2.jpg")

Search a folder for a matching face

DeepFace.find searches for the identity of an input image within a specified folder, s3 or ftp location. The README describes face recognition as applying verification many times across a set of images.

The example below points db_path at a folder called my_db. The function returns a list of pandas DataFrames.

  • img_path is the face you are looking for
  • db_path is the folder (or supported storage location) to search
dfs: List[pd.DataFrame] = DeepFace.find(img_path = "img1.jpg", db_path = "C:/my_db")

Store face embeddings in a database

For larger collections, DeepFace can register embeddings into a database instead of processing images on the fly or relying on local file structures. The README lists supported backends including postgres, pgvector, mongo, redis, sqlite and mysql, among others.

identify is the database-backed counterpart to verify for 1:1 checks. search is the database-backed counterpart to find for 1:N search, with optional approximate nearest neighbor support.

  • register adds images to the database
  • identify is the database alternative to verify
  • search is the database alternative to find
# register images into the database _ = DeepFace.register(img = "img1.jpg") _ = DeepFace.register(img = ["img2.jpg", "img3.jpg"])

Understand the pipeline behind the calls

The README describes five common stages in a face recognition pipeline: detect, align, normalize, represent and verify. DeepFace handles these in the background, so you can call a single function instead of building each stage yourself.

DeepFace wraps several existing models, including VGG-Face, FaceNet, OpenFace, DeepFace, DeepID, ArcFace, Dlib, SFace, GhostFaceNet and Buffalo_L. The README reports that these models reach and pass the 97.53% human accuracy figure it cites on facial recognition tasks.

What people use it for

  • Checking whether two photos in your own collection show the same person
  • Prototyping a face verification feature in a Python app
  • Finding matching faces across a local folder of images
  • Comparing several face recognition models through one interface
  • Running age, gender, emotion or race analysis on your own photos locally

Frequently asked questions

Is deepface free to use?

deepface is released under the MIT licence, as stated in the repository. The README does not list prices for any hosted service, though it mentions a managed API at deepface.dev as an option for people who do not want to manage infrastructure.

What do I need to run deepface?

The README lists Python and pip as prerequisites. It does not state a specific Python version in the excerpt, so check the PyPI page before installing.

Why does the install take so long or use so much disk space?

The default ONNX Runtime backend is described as a few hundred MB. The TensorFlow and PyTorch backends typically add one to several GB, so avoid those extras if disk space is limited.

What is the difference between verify and find?

verify compares two images and tells you whether they show the same person. find takes one image and searches a folder, s3 or ftp location for matching faces.

Can deepface be used in production for identification?

The README does not address compliance, consent or accuracy guarantees for production identification. Check the legal and accuracy requirements yourself before using it in a live system.

What are alternatives to deepface?

The project's comparable projects include face_recognition, InsightFace, DeepFaceLab and dlib. deepface's distinct feature is wrapping several models behind one interface.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

deepface suits Python developers, researchers and hobbyists who want face verification, search and attribute analysis without writing the deep learning code themselves. It is a poor fit for anyone who does not write Python or who needs a legally vetted biometric system, since the README does not cover compliance or accuracy guarantees for production use.

Install options & downloads