README

Face Recognition

_You can also read a translated version of this file in Chinese 简体中文版 or in Korean 한국어 or in Japanese 日本語._

Recognize and manipulate faces from Python or from the command line with
the world's simplest face recognition library.

Built using dlib's state-of-the-art face recognition
built with deep learning. The model has an accuracy of 99.38% on the
Labeled Faces in the Wild benchmark (see the LFW paper (PDF)).

This also provides a simple face_recognition command line tool that lets
you do face recognition on a folder of images from the command line!






 Features

 Find faces in pictures

Find all the faces that appear in a picture:

!

python
import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_locations = face_recognition.face_locations(image)


 Find and manipulate facial features in pictures

Get the locations and outlines of each person's eyes, nose, mouth and chin.

!

python
import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_landmarks_list = face_recognition.face_landmarks(image)


Finding facial features is super useful for lots of important stuff. But you can also use it for really stupid stuff
like applying digital make-up (think 'Meitu'):

!

 Identify faces in pictures

Recognize who appears in each photo.

!

python
import face_recognition
known_image = face_recognition.load_image_file("biden.jpg")
unknown_image = face_recognition.load_image_file("unknown.jpg")

biden_encoding = face_recognition.face_encodings(known_image)[0]
unknown_encoding = face_recognition.face_encodings(unknown_image)[0]

results = face_recognition.compare_faces([biden_encoding], unknown_encoding)


You can even use this library with other Python libraries to do real-time face recognition:

!

See this example for the code.

 Online Demos

User-contributed shared Jupyter notebook demo (not officially supported): 

 Installation

 Requirements

   Python 3.3+ or Python 2.7
   macOS or Linux (Windows not officially supported, but might work)

 Installation Options:

 Installing on Mac or Linux

First, make sure you have dlib already installed with Python bindings:

   How to install dlib from source on macOS or Ubuntu
  
Then, make sure you have cmake installed:  
 
brew install cmake

Finally, install this module from pypi using pip3 (or pip2 for Python 2):

bash
pip3 install face_recognition


Alternatively, you can try this library with Docker, see this section.

If you are having trouble with installation, you can also try out a
pre-configured VM.

 Installing on an Nvidia Jetson Nano board

  Jetson Nano installation instructions
    Please follow the instructions in the article carefully. There is current a bug in the CUDA libraries on the Jetson Nano that will cause this library to fail silently if you don't follow the instructions in the article to comment out a line in dlib and recompile it.

 Installing on Raspberry Pi 2+

   Raspberry Pi 2+ installation instruct

Top issues

Latest release

Added the face_detection CLI command
 Removed dependencies on scipy to make installation easier
 Cleaned up KNN example and fixed a bug with drawing fonts to label detected faces in the demo