{"id":8146,"library":"face-recognition","title":"Face Recognition","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/ageitgey/face_recognition","tags":["face recognition","computer vision","dlib","image processing","deep learning","facial landmarks"],"install":[{"cmd":"pip install face-recognition","lang":"bash","label":"Standard installation"},{"cmd":"# On Windows, first install CMake and C++ Build Tools (e.g., from Visual Studio Installer)\n# On Linux/macOS, ensure dlib prerequisites (build-essential, cmake) are installed\npip install cmake\npip install dlib\npip install face-recognition","lang":"bash","label":"Recommended installation (pre-install dlib/cmake)"}],"dependencies":[{"reason":"Core deep learning library for face detection and recognition algorithms. Its compilation often requires system-level build tools and CMake.","package":"dlib","optional":false},{"reason":"Fundamental package for numerical computation, especially for image array manipulation.","package":"numpy","optional":false},{"reason":"Contains the pre-trained models used by face-recognition. It's often installed automatically but sometimes needs explicit installation.","package":"face_recognition_models","optional":false},{"reason":"Required for building and installing dlib from source, which pip often attempts during face-recognition installation.","package":"cmake","optional":false},{"reason":"Used for image manipulation, particularly for drawing bounding boxes and facial features in examples.","package":"Pillow","optional":true},{"reason":"Required for real-time video processing examples and some webcam functionalities.","package":"opencv-python","optional":true}],"imports":[{"symbol":"face_recognition","correct":"import face_recognition"}],"quickstart":{"code":"import face_recognition\nimport os\n\n# Create a dummy image file for demonstration\n# In a real scenario, you would load an actual image.\n# You can replace 'my_picture.jpg' with a path to your own image.\n# For example, download one from the internet and save it.\nif not os.path.exists('my_picture.jpg'):\n    print(\"Please provide a 'my_picture.jpg' file in the current directory for the quickstart example.\")\n    # 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.\n    # For a truly runnable example without external files, one might generate a blank image or use base64 encoded data, but it complicates the quickstart.\n    exit()\n\nimage = face_recognition.load_image_file(\"my_picture.jpg\")\nface_locations = face_recognition.face_locations(image)\n\nprint(f\"Found {len(face_locations)} face(s) in this image.\")\n\nfor face_location in face_locations:\n    top, right, bottom, left = face_location\n    print(f\"A face is located at pixel location Top: {top}, Left: {left}, Bottom: {bottom}, Right: {right}\")\n\n# To demonstrate facial landmarks (eyes, nose, mouth, etc.)\nface_landmarks_list = face_recognition.face_landmarks(image)\n\nfor face_landmarks in face_landmarks_list:\n    print(\"Facial features for a face:\")\n    for facial_feature in face_landmarks.keys():\n        print(f\"- The {facial_feature} in this face has the following points: {face_landmarks[facial_feature]}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"Python 3.11+"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `face-recognition` library's model is primarily trained on adult faces and may not perform optimally or accurately when recognizing children.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"dlib requires C++ build tools and CMake to compile during installation, which are often missing or misconfigured on the system.","error":"ERROR: Failed building wheel for dlib"},{"fix":"Upgrade `dlib` to version 19.7 or newer: `pip install --upgrade dlib`.","cause":"The installed version of `dlib` is too old and lacks the required models or functions.","error":"AttributeError: 'module' object has no attribute 'face_recognition_model_v1' (or 'cnn_face_detection_model_v1')"},{"fix":"Run `pip install face_recognition_models` to install the required models.","cause":"The `face_recognition_models` package, which contains the necessary trained models, is not installed or accessible in the current Python environment.","error":"Please install `face_recognition_models` with this command before using `face_recognition`"},{"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.","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).","error":"Illegal instruction (core dumped)"},{"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.","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.","error":"RuntimeError: Unsupported image type, must be 8bit gray or RGB image."}]}