{"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":"python","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,"search_vec":"'1.3.0':57 'accuraci':42 'add':63 'address':68 'api':14 'art':36 'command':50 'command-lin':49 'compat':69 'comput':80 'core':75 'current':54 'deep':37,85 'depend':76 'detect':17 'dlib':30,77,82 'face':1,4,22,78 'face-recognit':3 'facial':16,18,87 'featur':64 'high':41 'imag':25,83 'improv':65 'interfac':52 'issu':70 'landmark':19,88 'learn':38,86 'leverag':29 'librari':9 'line':51 'local':20 'model':39 'modul':47 'occur':60 'offer':44 'often':71 'perform':66 'period':61 'process':84 'provid':11 'python':8,46 'recognit':2,5,23,79 'releas':59 'state':33 'state-of-the-art':32 'straightforward':13 'tie':72 'version':55 'video':27 'vision':81","created_at":"2026-04-16T17:00:41.312871+00:00","updated_at":"2026-04-16T17:00:41.312871+00:00","problems":{"verify_error":"install timed out after 120s"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.0","cli_name":"face_recognition","cli_version":"","type":"library","homepage":null,"github":"https://github.com/ageitgey/face_recognition","docs":null,"changelog":null,"pypi":"https://pypi.org/project/face-recognition/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"timeout","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}