{"id":4499,"library":"deepface","title":"DeepFace","description":"DeepFace is an open-source Python library for lightweight face recognition and facial attribute analysis (age, gender, emotion, and race). It acts as a hybrid framework, wrapping 11 state-of-the-art models into a single, easy-to-use interface. The library is actively maintained with frequent releases, often on a weekly or bi-weekly basis, and supports Python 3.7+.","status":"active","version":"0.0.99","language":"en","source_language":"en","source_url":"https://github.com/serengil/deepface","tags":["face recognition","facial analysis","deep learning","computer vision","biometrics","image processing","mlops"],"install":[{"cmd":"pip install deepface","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core deep learning backend for models.","package":"tensorflow"},{"reason":"Essential for image processing, face detection, and alignment.","package":"opencv-python"},{"reason":"Fundamental package for numerical operations.","package":"numpy"},{"reason":"Data manipulation and analysis, often used for results.","package":"pandas"},{"reason":"Used for downloading pre-trained models from Google Drive.","package":"gdown"},{"reason":"Progress bars for model downloads and processing.","package":"tqdm"},{"reason":"Image processing utility.","package":"Pillow"},{"reason":"HTTP client for various internal operations.","package":"requests"},{"reason":"For the optional DeepFace API server.","package":"Flask","optional":true},{"reason":"Dependency for Flask, for the optional DeepFace API server.","package":"Werkzeug","optional":true},{"reason":"Optional backend for vector database integration with PostgreSQL for the `find` function.","package":"pgvector","optional":true},{"reason":"Optional backend for vector database integration with Pinecone for the `find` function.","package":"pinecone-client","optional":true},{"reason":"Optional backend for vector database integration with MongoDB for the `find` function.","package":"pymongo","optional":true},{"reason":"Optional backend for vector database integration with Weaviate for the `find` function.","package":"weaviate-client","optional":true}],"imports":[{"symbol":"DeepFace","correct":"from deepface import DeepFace"}],"quickstart":{"code":"import os\nimport cv2\nimport numpy as np\nfrom deepface import DeepFace\n\n# Create dummy image files for demonstration\n# In a real scenario, these would be actual image paths\nimg1_path = \"img1.jpg\"\nimg2_path = \"img2.jpg\"\nperson_img_path = \"person.jpg\"\n\n# Generate dummy images (replace with actual image files for real usage)\nif not os.path.exists(img1_path):\n    cv2.imwrite(img1_path, np.zeros((224, 224, 3), dtype=np.uint8) + 100)\nif not os.path.exists(img2_path):\n    cv2.imwrite(img2_path, np.zeros((224, 224, 3), dtype=np.uint8) + 150)\nif not os.path.exists(person_img_path):\n    cv2.imwrite(person_img_path, np.zeros((224, 224, 3), dtype=np.uint8) + 200)\n\ntry:\n    # Verify two faces\n    result_verify = DeepFace.verify(img1_path, img2_path)\n    print(\"Face Verification Result:\", result_verify)\n\n    # Analyze facial attributes\n    analysis_result = DeepFace.analyze(person_img_path, actions=['age', 'gender', 'emotion', 'race'])\n    print(\"\\nFacial Analysis Result:\", analysis_result)\n\n    # Generate a face embedding (representation)\n    embedding = DeepFace.represent(img1_path)\n    print(\"\\nFace Embedding (first 5 elements of first face):\", embedding[0]['embedding'][:5])\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure you have valid image files at the specified paths.\")\n    print(\"Also, DeepFace downloads models on first run, requiring an internet connection.\")\n\n# Clean up dummy images (optional)\n# os.remove(img1_path)\n# os.remove(img2_path)\n# os.remove(person_img_path)","lang":"python","description":"This quickstart demonstrates the core functionalities of DeepFace: face verification, facial attribute analysis (age, gender, emotion, race), and generating face embeddings. It uses dummy image files for immediate execution, but in a real application, you would provide paths to actual face images. Note that DeepFace will automatically download necessary deep learning models on its first execution, which requires an active internet connection and may take some time."},"warnings":[{"fix":"Review and update code that processes facial landmark return values to handle raw Python data types instead of previous object structures.","message":"In `v0.0.97`, return types for facial landmarks were changed to raw Python types. Code that previously relied on specific object structures for landmark data might require updates to parse the new raw types.","severity":"breaking","affected_versions":">=0.0.97"},{"fix":"Adjust any direct imports or references from `training.Model` to `Model` if interacting with ArcFace's internal model structure.","message":"In `v0.0.96`, the internal reference `training.Model` was replaced with `Model` within the ArcFace model. Users who had custom code directly importing or referencing `training.Model` from DeepFace's internal modules for ArcFace might experience import errors or unexpected behavior.","severity":"breaking","affected_versions":">=0.0.96"},{"fix":"Ensure an internet connection is available during the first execution. Consider pre-downloading models in deployment environments or during application setup if offline operation is critical.","message":"DeepFace automatically downloads several large pre-trained deep learning models on the first execution of certain functions (e.g., `verify`, `analyze`). This process requires an active internet connection and can lead to a significant delay during the initial run.","severity":"gotcha","affected_versions":"All"},{"fix":"Provide high-quality, well-lit, frontal images whenever possible. Implement pre-processing steps to improve image quality or reject unsuitable inputs if strict accuracy is required.","message":"Accuracy of face recognition and analysis can degrade significantly with poor image quality, sub-optimal lighting conditions, occlusions (e.g., masks, sunglasses), or non-frontal face angles. Performance claims are often based on ideal, high-quality inputs.","severity":"gotcha","affected_versions":"All"},{"fix":"Install the specific database client package(s) for the chosen backend (e.g., `pip install pgvector`) in addition to `deepface` if you plan to use database integration for the `find` function.","message":"For advanced features like storing and searching face embeddings in vector databases (e.g., PgVector, Pinecone, MongoDB, Weaviate), the corresponding database client packages must be installed separately. `pip install deepface` alone does not include these optional dependencies.","severity":"gotcha","affected_versions":">=0.0.98"},{"fix":"If automatic database refreshing is not desired, explicitly set `refresh_database=False` when calling the `DeepFace.find()` function.","message":"Starting from `v0.0.92`, the `find` function's `refresh_database` argument defaults to `True`. If your application's logic or performance relied on the `find` function *not* automatically refreshing its internal database by default, this change could introduce unexpected re-indexing times.","severity":"gotcha","affected_versions":">=0.0.92"},{"fix":"Be aware of these limitations when relying on age prediction. Consider using age ranges rather than exact age, and optimize for clear, frontal images where possible.","message":"Age prediction accuracy can be variable, particularly for older individuals where it may underestimate age. Performance can also be highly dependent on the quality and type of input image, performing best with clear, head-on shots.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}