deepface-basic-usage
Basic usage guide for the DeepFace library (face recognition, verification, analysis).
Best use case
deepface-basic-usage is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Basic usage guide for the DeepFace library (face recognition, verification, analysis).
Teams using deepface-basic-usage should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/deepface-basic-usage/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How deepface-basic-usage Compares
| Feature / Agent | deepface-basic-usage | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Basic usage guide for the DeepFace library (face recognition, verification, analysis).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Skill: DeepFace Basic Usage
This skill provides a quick reference and guide for using the `deepface` library for face recognition tasks.
## Overview
DeepFace is a hybrid face recognition framework for Python that wraps state-of-the-art models (VGG-Face, FaceNet, ArcFace, etc.) and detectors (RetinaFace, MtCNN, YOLO, etc.).
## Installation
```bash
pip install deepface
# Or with pixi
pixi add deepface
```
## Core Functions
Import:
```python
from deepface import DeepFace
```
### 1. Face Verification (1:1)
Determines if two images belong to the same person.
```python
result = DeepFace.verify(
img1_path = "img1.jpg",
img2_path = "img2.jpg",
model_name = "VGG-Face", # Optional: see Model Selection below
detector_backend = "opencv", # Optional: see Detector Selection below
distance_metric = "cosine", # Optional: cosine, euclidean, euclidean_l2
align = True, # Optional: Align faces before verification
)
# result is a dict:
# {
# "verified": True,
# "distance": 0.256,
# "threshold": 0.40,
# "model": "VGG-Face",
# "detector_backend": "opencv",
# "similarity_metric": "cosine",
# "facial_areas": {"img1": {...}, "img2": {...}},
# "time": 1.23
# }
```
### 2. Face Recognition / Search (1:N)
Finds identity of an input image in a database (folder of images).
**Directory-based (`find`)**:
```python
dfs = DeepFace.find(
img_path = "img.jpg",
db_path = "/path/to/images_folder",
model_name = "VGG-Face",
detector_backend = "opencv"
)
# Returns a list of pandas DataFrames (one per face detected in input)
```
**Database-backed (`search`)**:
Supports backends like Postgres (pgvector), Pinecone, Milvus, Weaviate, etc.
```python
# Register
DeepFace.register(img="img1.jpg")
# Search
dfs = DeepFace.search(img="target.jpg")
```
### 3. Facial Attribute Analysis
Predicts age, gender, race, and emotion.
```python
objs = DeepFace.analyze(
img_path = "img.jpg",
actions = ['age', 'gender', 'race', 'emotion'],
detector_backend = "opencv"
)
# Returns a list of dicts (one per face)
```
### 4. Embeddings (Representation)
Get the vector representation of a face.
```python
embedding_objs = DeepFace.represent(
img_path = "img.jpg",
model_name = "VGG-Face",
detector_backend = "opencv"
)
# Returns list of dicts:
# [
# {
# "embedding": [0.1, 0.5, ...],
# "facial_area": {...}
# }
# ]
```
## Configuration Options
### Available Models
`VGG-Face` (default), `Facenet`, `Facenet512`, `OpenFace`, `DeepFace`, `DeepID`, `ArcFace`, `Dlib`, `SFace`, `GhostFaceNet`.
*Recommendation:*
- **Accuracy**: `ArcFace`, `Facenet512`, `VGG-Face`
- **Legacy/Lower Accuracy**: `DeepFace`, `OpenFace`
### Available Detectors
`opencv` (default, fast), `ssd`, `dlib`, `mtcnn`, `retinaface` (highly accurate), `mediapipe`, `yolov8`, `centerface`.
*Recommendation:*
- **Speed**: `opencv`, `ssd`
- **Accuracy**: `retinaface`, `mtcnn`
### Distance Metrics
`cosine` (default), `euclidean`, `euclidean_l2`.
## Common Issues & Tips
1. **Dependencies**: DeepFace installs many dependencies (tensorflow/keras or pytorch depending on model). Ensure your environment is set up correctly.
2. **Weights Download**: First run will download model weights to `~/.deepface/weights`.
3. **Face Not Found**: If no face is detected, functions may raise `ValueError`. Set `enforce_detection=False` to skip detection (treats whole image as face) or handle the exception.
```python
DeepFace.verify(..., enforce_detection=False)
```
4. **Backend Compatibility**: If using specialized detectors (like `retinaface` or `dlib`), ensure their specific pip packages are installed.Related Skills
pei-docker-usage
Helper for PeiDocker (`pei-docker-cli`). Trigger ONLY when the user explicitly requests PeiDocker usage OR when working within a PeiDocker-generated project (indicated by `user_config.yml`).
conan-basic-usage
Basic operations for the Conan C++ package manager. Use when the user explicitly asks to 'use conan' for tasks like creating projects, installing dependencies, or building packages, or asks for 'how to' guidance on Conan setup.
pixi-make-offline-channel
Use when the user wants to create a self-hosted, offline-installable Conda channel (mirror) containing a specific subset of packages using Pixi.
pixi-make-cu-build-env
Guides the agent to setup a new or existing Pixi environment for compiling C++ and CUDA code. It ensures the correct compilers, toolkits, and CMake configurations are in place for a robust user-space build.
pixi-install-nvidia
Use when the user says "use pixi to install <some nvidia tool>" (or similar) and wants NVIDIA/CUDA/GPU packages installed via Pixi (no sudo/apt), e.g., CUDA toolkit pieces, cuDNN/NCCL, PyTorch CUDA builds, RAPIDS.
explore-dnn-model
Manual invocation only; use only when the user explicitly requests `explore-dnn-model` by name. Explore how to run a given DNN model checkpoint in the current Python environment by locating weights + upstream source code, resolving dependencies with user confirmation, running reproducible experiments under `tmp/`, and producing reports about I/O contracts, timing, and profiling.
openspec-ext-revise-by-decision
Manual invocation only; use only when the user explicitly requests `openspec-ext-revise-by-decision` by exact name. Revise OpenSpec change artifacts from a review or decision document that contains questions plus `DECISION` blocks, applying chosen decisions from a review file such as `openspec/changes/<change>/review/review-*.md` back into proposal, design, specs, and tasks.
openspec-ext-review-plan
Review an OpenSpec change (or a single OpenSpec change artifact file) for completeness, coherence, and alignment with existing system design; capture actionable feedback plus open questions; write a review report under the change directory (review/review-YYYYMMDD-HHMMSS.md).
openspec-ext-respond-to-review
Read an OpenSpec review report critically, evaluate the reviewer's proposals and findings against the current change artifacts and repository context, and write developer-owned final decisions/responses back into the review document. Use when the user explicitly mentions `openspec` or points to a path under `openspec/` while asking to examine a review report carefully, decide open questions, respond to findings, fill `DECISION` blocks, respond to an OpenSpec review file, or record final answers in an OpenSpec review document without yet revising the proposal, design, specs, or tasks.
openspec-ext-hack-through-test
Manual invocation only. OpenSpec-specific hack-through-testing workflow targeting production-level end-to-end paths using real data and real user workflows — not CI smoke/unit/integration tests. Three subskills: `propose` to create an OpenSpec change with HTT-ready test cases (automatic scripts and interactive guides) by invoking `openspec-propose` or `openspec-ff-change`, `revise` to update an existing OpenSpec change so its artifacts support hack-through-testing-driven implementation and testing, and `run` to exercise an implemented OpenSpec change through the full hack-through-testing loop (in-place by default, or in a disposable snapshot worktree when requested). Use when the user explicitly asks for `openspec-ext-hack-through-test`, points to `openspec/changes/...` while asking to propose, revise, run, exercise, or prepare work under hack-through-testing principles, or wants OpenSpec work shaped for fast blocker discovery through patch-forward testing.
openspec-ext-explain
Create or update OpenSpec change explanation docs that capture developer-facing questions and answers under `openspec/changes/.../explain/`. Use when the user explicitly mentions `openspec` or points to a path under `openspec/` while asking to create, update, document, or maintain a Q&A, FAQ, explain note, or question-and-answer doc for an OpenSpec change based on user questions, implementation notes, review questions, or current chat context.
test-and-log
Test a target (script, demo, pipeline, CLI command, integration) without modifying any source code, then write a structured log of the process, outcomes, anomalies, and issues. Use when the user says "test X and log", "run X and document findings", or "try X without changing code". Default log location is context/logs/TIMESTAMP-task-name/TIMESTAMP.md.