Face Recognition

1.3.0 · active · verified Thu Apr 16

face-recognition is a Python library that provides a straightforward API for facial detection, facial landmark localization, and face recognition from images and video. It leverages dlib's state-of-the-art deep learning models for high accuracy and offers both Python module and command-line interfaces. The current version is 1.3.0, and releases occur periodically to add features, improve performance, and address compatibility issues, often tied to its core dependency, dlib.

Common errors

```
ERROR: Failed building wheel for dlib
```
cause dlib requires C++ build tools and CMake to compile during installation, which are often missing or misconfigured on the system.

fix On Windows: Install Visual Studio with 'Desktop development with C++' workload. On Linux: `sudo apt-get install build-essential cmake`. Ensure CMake is installed and added to your system's PATH, then try `pip install cmake` followed by `pip install dlib` before `pip install face-recognition`.
```
AttributeError: 'module' object has no attribute 'face_recognition_model_v1' (or 'cnn_face_detection_model_v1')
```
cause The installed version of `dlib` is too old and lacks the required models or functions.

fix Upgrade `dlib` to version 19.7 or newer: `pip install --upgrade dlib`.
```
Please install `face_recognition_models` with this command before using `face_recognition`
```
cause The `face_recognition_models` package, which contains the necessary trained models, is not installed or accessible in the current Python environment.

fix Run `pip install face_recognition_models` to install the required models.
```
Illegal instruction (core dumped)
```
cause dlib might be compiled with CPU instruction set extensions (like SSE4 or AVX) that your CPU does not support (e.g., an older CPU).

fix You may need to recompile dlib from source with specific flags to disable unsupported instruction sets. This often involves modifying dlib's build configuration or using a dlib version specifically compiled for older CPUs. Refer to dlib's official documentation for detailed compilation instructions.
```
RuntimeError: Unsupported image type, must be 8bit gray or RGB image.
```
cause This error typically occurs when using webcam examples or integrating with OpenCV, indicating that the image or video frame is not in the expected 8-bit grayscale or RGB format. This often points to an issue with OpenCV's webcam setup or image reading.

fix Ensure your webcam is correctly configured and that image loading/conversion (e.g., BGR to RGB if using OpenCV) is handled properly. Check OpenCV installation and webcam drivers.

Warnings

gotcha Installing the `dlib` dependency, which is written in C++, is often complex and prone to errors, especially on Windows or certain Linux distributions. It typically requires CMake and C++ build tools (e.g., Visual Studio Build Tools on Windows, `build-essential` on Linux).
Fix: Before `pip install face-recognition`, ensure CMake is installed and in your system PATH, and that C++ development tools are properly set up for your OS. It's often recommended to `pip install cmake` and `pip install dlib` separately before `pip install face-recognition`. Consider using a virtual environment.
breaking Some Python versions, particularly newer ones like 3.11+, may experience installation issues with `dlib` (and by extension `face-recognition`) due to `dlib`'s reliance on legacy `setup.py` build mechanisms.
Fix: Consider using Python 3.9 or 3.10 if encountering persistent build errors. Alternatively, try installing a pre-compiled `dlib` wheel (`.whl` file) compatible with your Python version and OS before installing `face-recognition`.
gotcha Deployment to cloud hosting providers (e.g., Heroku, AWS, Streamlit Cloud) can be challenging because `dlib`'s compilation requires significant RAM, often exceeding default limits (e.g., 1GB on Streamlit Cloud) and resulting in Out-Of-Memory (OOM) errors.
Fix: For cloud deployments, consider using a Docker image with pre-compiled `dlib` and `face-recognition`, or a `dlib-bin` package (if available) as a dependency. Some users have found success by forking the repository and replacing the `dlib` dependency with `dlib-bin` in `setup.py`.
gotcha The `face-recognition` library's model is primarily trained on adult faces and may not perform optimally or accurately when recognizing children.
Fix: Be aware of this limitation when applying the library to datasets containing children. Custom training or fine-tuning on child-specific datasets would be required for better performance, but this is beyond the scope of this library's direct functionality.

Install

pip install face-recognition Standard installation
# On Windows, first install CMake and C++ Build Tools (e.g., from Visual Studio Installer) # On Linux/macOS, ensure dlib prerequisites (build-essential, cmake) are installed pip install cmake pip install dlib pip install face-recognition Recommended installation (pre-install dlib/cmake)

Imports

face_recognition
```
import face_recognition
```

Quickstart

This quickstart demonstrates how to load an image and find all faces within it, returning their bounding box coordinates. It also shows how to locate key facial features (landmarks) like eyes, nose, and mouth. Ensure you have an image file named `my_picture.jpg` in the same directory as your script, or update the path accordingly.

import face_recognition
import os

# Create a dummy image file for demonstration
# In a real scenario, you would load an actual image.
# You can replace 'my_picture.jpg' with a path to your own image.
# For example, download one from the internet and save it.
if not os.path.exists('my_picture.jpg'):
    print("Please provide a 'my_picture.jpg' file in the current directory for the quickstart example.")
    # Exit or create a placeholder if it's strictly necessary for execution, but for a quickstart, it's better to tell user to provide one.
    # For a truly runnable example without external files, one might generate a blank image or use base64 encoded data, but it complicates the quickstart.
    exit()

image = face_recognition.load_image_file("my_picture.jpg")
face_locations = face_recognition.face_locations(image)

print(f"Found {len(face_locations)} face(s) in this image.")

for face_location in face_locations:
    top, right, bottom, left = face_location
    print(f"A face is located at pixel location Top: {top}, Left: {left}, Bottom: {bottom}, Right: {right}")

# To demonstrate facial landmarks (eyes, nose, mouth, etc.)
face_landmarks_list = face_recognition.face_landmarks(image)

for face_landmarks in face_landmarks_list:
    print("Facial features for a face:")
    for facial_feature in face_landmarks.keys():
        print(f"- The {facial_feature} in this face has the following points: {face_landmarks[facial_feature]}")

view raw JSON →