serengil/deepface

deepface – Python library for face recognition & analysis

What it is – deepface is a lightweight, all‑in‑one Python package that wraps a collection of state‑of‑the‑art face‑recognition models (VGG‑Face, FaceNet, ArcFace, Dlib, etc.) and provides a simple, high‑level API for the whole face‑processing pipeline: detection, alignment, embedding, verification, search, and attribute analysis (age, gender, emotion, race, anti‑spoofing). It can run on TensorFlow or PyTorch and also ships a REST API and Docker image for service‑oriented use.

---

Key capabilities (as described in the README)

Capability	How you use it	What you get
Face verification	DeepFace.verify(img1_path, img2_path)	{"verified": true/false, ...}
1‑to‑N recognition	DeepFace.find(img_path, db_path)	List of pandas DataFrames with similarity scores
Database‑backed search	Register faces with DeepFace.register(), then DeepFace.identify() / DeepFace.search()	Fast vector‑search against Postgres, Mongo, Neo4j, Pinecone, Milvus, Qdrant, Weaviate, etc.
Attribute analysis	DeepFace.analyze(img_path, actions=["age","gender","race","emotion"])	List of dicts with predicted age, gender, race, emotion
Real‑time webcam stream	DeepFace.stream(db_path=…)	Live window showing detection, verification and attributes
Embedding extraction	DeepFace.represent(img_path)	Vector embeddings for downstream tasks
Anti‑spoofing	anti_spoofing=True in any call	Boolean flag is_real per detected face
Pluggable detectors	Choose from OpenCV, SSD, MTCNN, RetinaFace, MediaPipe, YOLO‑v8/‑v11/‑v12, YuNet, CenterFace, etc.	Trade‑off between speed and accuracy
REST API / Docker	Run scripts/service.sh or scripts/dockerize.sh	HTTP endpoints that accept files, URLs or base64 images

---

Installation

# TensorFlow backend (default)
pip install "deepface[tensorflow]"
# or PyTorch backend
pip install "deepface[pytorch]"

You can also install directly from source:

git clone https://github.com/serengil/deepface.git
cd deepface
pip install -e .[tensorflow]   # or .[pytorch]

A managed cloud API is available at deepface.dev for those who prefer not to run the library locally.

---

Quick‑start code snippets

from deepface import DeepFace

# 1️⃣ Verify two pictures
result = DeepFace.verify("img1.jpg", "img2.jpg")
print(result["verified"])  # True / False

# 2️⃣ Find a person in a folder
matches = DeepFace.find(img_path="query.jpg", db_path="/my_db")
print(matches[0].head())

# 3️⃣ Analyze attributes
attrs = DeepFace.analyze("person.jpg", actions=["age","gender","emotion","race"])
print(attrs)

# 4️⃣ Extract embedding vector
emb = DeepFace.represent("face.jpg")
print(emb[0]["embedding"].shape)  # e.g. (128,)

All functions accept optional arguments to switch the underlying model (model_name), detector (detector_backend), distance metric, and whether to run anti‑spoofing.

---

Ecosystem & Extensibility

• Model portfolio – 12 pre‑trained models are bundled; you can pick any via model_name.
• Vector‑DB integration – native support for PostgreSQL (pgvector), MongoDB, Neo4j, Pinecone, Milvus, Qdrant, Weaviate, enabling large‑scale searchable galleries.
• Front‑end demo – a separate deepface-react-ui repo provides a React UI that talks to the Python API.
• Docker & Gunicorn – ready‑to‑run container (docker pull serengil/deepface) for micro‑service deployment.
• Benchmarks – a benchmarks folder lists accuracy numbers and speed comparisons for models and detectors.

---

Maturity & Community

• Stars: ~ 10 k+ on GitHub, indicating strong community interest.
• Downloads: > hundreds of thousands via PyPI (badge shown).
• Docker pulls: substantial, showing adoption in production‑style setups.
• Documentation: extensive README with links to tutorials, YouTube demos, and a DOI for a formal paper.
• Active maintenance: installation extras, frequent releases, and a public issue tracker.

---

License

MIT – permissive open‑source license allowing commercial and academic use.

---

Bottom line

deepface turns complex face‑recognition pipelines into a few‑line Python calls while still giving power users control over models, detectors, and vector‑database back‑ends. It is well‑documented, actively maintained, and suitable for everything from quick prototypes to production‑grade services.