DeepFace Repo Skill

Use this skill when a task names deepface, DeepFace, face verification, facial recognition, face embeddings, face detection, facial attribute analysis, anti-spoofing, DeepFace REST API routes, or DeepFace datastore/database search.

DeepFace is a Python face-recognition and facial-analysis package. It wraps recognition models, detector backends, demographic models, a folder-backed face datastore, database-backed register/search APIs, a Flask/Gunicorn service, and webcam/video streaming helpers.

Quick Start

Install the public package for application work:

pip install deepface
python -c "from deepface import DeepFace; print('DeepFace import ok')"

If TensorFlow is new enough to use Keras 3 behavior and from deepface import DeepFace fails with No module named 'tf_keras', install the compatibility package:

pip install tf-keras

Run the bundled diagnostic before deeper troubleshooting:

python scripts/check_deepface_environment.py --json

The diagnostic prints package versions, supported models/detectors, database backends, and import health. It does not build models, download weights, connect to databases, or require a GPU.

Route By Task

• Verification, embeddings, and local folder search: use sub-skills/recognition-workflows/SKILL.md for DeepFace.verify, DeepFace.represent, DeepFace.find, distance metrics, thresholds, confidence, precomputed embeddings, batch representation, local folder datastores, and signed pickle handling.
• Face extraction, detectors, demographics, and anti-spoofing: use sub-skills/detection-and-demography/SKILL.md for DeepFace.extract_faces, DeepFace.analyze, detector backend choices, enforce_detection, align, expand_percentage, landmark outputs, age/gender/race/emotion actions, and anti-spoofing failure handling.
• Database-backed register/search: use sub-skills/datastore-search/SKILL.md for DeepFace.register, DeepFace.search, DeepFace.build_index, exact versus ANN search, Postgres/Mongo/vector database backends, connection details, and optional database client dependencies.
• REST API and streaming: use sub-skills/api-service/SKILL.md for the Flask/Gunicorn API, /verify, /represent, /analyze, /register, /search, /build/index, bearer auth, JSON/form/file uploads, Docker/service deployment, and DeepFace.stream webcam/video guidance.
• Models, detectors, dependencies, and weights: use sub-skills/model-and-backend-selection/SKILL.md for supported recognition/demography/spoofing/detector model names, optional detector packages, TensorFlow/Keras compatibility, model-weight downloads, CPU/GPU expectations, normalization, and encrypted embeddings.

Shared References And Helpers

• references/package-overview.md summarizes the public API facade, architecture, and cross-skill concepts.
• references/troubleshooting.md covers install/import, TensorFlow/Keras, weight cache, input, optional dependency, API, and backend failures that cut across workflows.
• references/repo-provenance.md records the source revision, package version, and evidence paths used to create this skill.
• references/repo-routing-metadata.json contains structured routing metadata for managed repo-skill import; this creation run did not import the skill.
• scripts/check_deepface_environment.py verifies an installed DeepFace environment without model downloads or database connections.

Common Decision Points

• Use the default model_name="VGG-Face", detector_backend="opencv", and distance_metric="cosine" for simple CPU examples unless the user names another model or detector.
• Set enforce_detection=False only when the user accepts full-image fallback behavior for hard or non-face inputs; otherwise treat FaceNotDetected as a data-quality signal.
• Do not recommend optional detectors such as Dlib, MediaPipe, YOLO, FastMTCNN, or Buffalo_L until the matching optional package is installed and the user accepts model-weight downloads.
• Use folder-backed DeepFace.find for local image directories; use database-backed register/search/build_index only when the user has a configured database service and optional client dependencies.
• Treat model weights, remote image URLs, and API requests as network operations. Ask before running them in constrained/offline environments.

Safety And Self-Containment

This generated skill is self-contained. Runtime instructions, references, and helper scripts live inside this skill directory. Original repository files, tests, notebooks, and scripts were used only as evidence and are not runtime dependencies for future agents.