Guide · Open source
How to use face_recognition: install, detect and match faces
Updated · written with AI from the project's own documentation and checked against our catalogue data
face_recognition is an open-source Python library and command-line tool that finds faces in photos, locates features such as eyes and nose, and checks whether two images show the same person. This guide is for Python developers and hobbyists who want to sort or label a folder of photos. By the end you will know what to install, how to run the command-line tools and how to adjust the match tolerance.
face_recognitionageitgey/face_recognition · ★ 56.9k · MIT Install options & downloads Quick start
- 1Install dlib with Python bindings. Follow the README's linked guide to install dlib with Python bindings before anything else.
- 2Install cmake. On macOS, run brew install cmake. Cmake is required before the library install.
- 3Install face_recognition. Run pip3 install face_recognition to install the library from PyPI.
- 4Load and detect faces. Use load_image_file and face_locations in Python to find faces in an image.
- 5Set up known and unknown folders. Put one named picture per known person in one folder, and the photos to check in another.
- 6Run the command and tune tolerance. Run face_recognition on both folders, then adjust --tolerance if you see repeated wrong matches.
What face_recognition does and what it needs
The library is built on dlib's deep-learning face recognition model, which the README reports at 99.38% accuracy on the Labeled Faces in the Wild benchmark. It is licensed under MIT and written in Python.
The README lists Python 3.3+ (or Python 2.7) and macOS or Linux as requirements. Windows is not officially supported, though the README links community install guides.
- Python 3.3+ or Python 2.7
- macOS or Linux (Windows not officially supported)
- dlib with Python bindings, installed first
- cmake
Install dlib, cmake and face_recognition on Mac or Linux
Install dlib with Python bindings before anything else. The README links to a guide on installing dlib from source on macOS or Ubuntu. Then install cmake; on macOS the README uses Homebrew.
Finally, install the library from PyPI with pip3. Use pip2 only if you are on Python 2.7.
- Install dlib with Python bindings first (see the linked guide in the README)
- Install cmake
brew install cmake
pip3 install face_recognitionDetect faces and facial features in Python
Load an image with load_image_file, then call face_locations to get the position of every face. The README also shows face_landmarks, which returns the outlines of each person's eyes, nose, mouth and chin.
- face_locations(image) finds faces in a picture
- face_landmarks(image) returns facial feature outlines
import face_recognition
image = face_recognition.load_image_file("your_file.jpg")
face_locations = face_recognition.face_locations(image)Compare two faces in Python
To check whether two photos show the same person, encode the face in each image with face_encodings, then pass the encodings to compare_faces. The example takes the first face found in each image, so use images with one clear face when you test.
compare_faces returns a list of results, one per known encoding.
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)Label people in a folder with the face_recognition command
Create one folder with one picture per known person, named after that person. Create a second folder with the photos you want to identify. Then run face_recognition with both folders. Each output line is comma-separated: the filename, then the name found. Faces that match no one are reported as unknown_person.
face_detection works the same way but only reports pixel coordinates (top, right, bottom, left) for each face it finds.
- Known folder: one image per person, file named after the person
- Unknown folder: the photos to label, or a single image
$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/Adjust tolerance to reduce wrong matches
If one person is matched to several people, their photos may look very similar. The default tolerance is 0.6, and lower values make comparisons stricter. Use --show-distance true to see the distance behind each match and choose a value from that.
The README example uses 0.54, but it is only an example; the right value depends on your photos.
- Default tolerance: 0.6
- Lower tolerance = stricter matching
- --show-distance true prints the distance for each match
$ face_recognition --tolerance 0.54 ./pictures_of_people_i_know/ ./unknown_pictures/
$ face_recognition --show-distance true ./pictures_of_people_i_know/ ./unknown_pictures/What people use it for
- Sorting a folder of personal photos by who appears in them
- Adding face detection to a small Python script or app
- Building a simple baseline face recognition pipeline for research
- Finding the pixel coordinates of faces in a batch of images with face_detection
Frequently asked questions
Is face_recognition free to use?
The project is released under the MIT licence, as stated in the repository. Check the licence file for the full terms before using it in a product.
Does face_recognition work on Windows?
The README says Windows is not officially supported but might work. It links a community install guide, so expect extra setup work.
Why is face_recognition hard to install?
The README says installation is the hardest part. You need dlib with Python bindings and cmake before installing the library from PyPI.
What Python version do I need for face_recognition?
The README lists Python 3.3+ and also mentions Python 2.7. Use pip3 on Python 3.
What does the tolerance setting do in face_recognition?
The default tolerance is 0.6. Lower values make face comparisons stricter, which can reduce wrong matches between similar-looking people.
What are alternatives to face_recognition?
Comparable projects include DeepFace, InsightFace, the OpenCV face module and MTCNN. This page does not compare their accuracy or speed.
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
Use face_recognition if you are a Python developer or hobbyist who wants a simple way to detect and match faces in your own photos on Mac or Linux. Pick another tool if you need official Windows support, want to avoid building dlib and cmake, or plan to identify people without their consent.
Install options & downloads