# ageitgey/face_recognition architecture

> Architecture diagram of the GitHub repository ageitgey/face_recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ageitgey/face_recognition
- Repository: https://github.com/ageitgey/face_recognition

## Overview

Face Recognition is a Python library and pair of command-line tools for detecting faces, extracting facial features and encodings, and matching faces. In the Python workflow, a caller loads an image, detects faces, optionally gets landmarks and encodings, then compares encodings. The recognition CLI builds known-person encodings from filenames and tests unknown images; a separate CLI reports face coordinates. The API delegates detection and landmark prediction to dlib. Source excerpts establish these calls, but do not show every model initialization or the full implementation.

Main entry points: [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py) (Landmark extraction), [`face_recognition/face_recognition_cli.py`](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py) (Unknown image test), [`face_recognition/face_detection_cli.py`](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_detection_cli.py) (Detection image test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_recognition_cli["Recognition CLI"]
  node_known_people_scan["Known face scan"]
  node_unknown_image_test["Unknown image test"]
  node_detection_cli["Detection CLI"]
  node_detection_image_test["Detection image test"]
end

subgraph group_analysis["Face analysis"]
  node_image_loading["Image loading<br/>[api.py]"]
  node_face_detection["Face detection<br/>[api.py]"]
  node_landmark_extraction["Landmark extraction<br/>[api.py]"]
end

subgraph group_matching["Face matching"]
  node_encoding["Face encoding<br/>[api.py]"]
  node_face_comparison["Face comparison<br/>[api.py]"]
end

node_python_user(("Python caller"))
node_cli_user(("CLI user"))
node_dlib{{"dlib"}}
node_face_models{{"Face models"}}

node_python_user -->|"loads image"| node_image_loading
node_python_user -->|"requests locations"| node_face_detection
node_python_user -->|"requests landmarks"| node_landmark_extraction
node_python_user -->|"requests encodings"| node_encoding
node_python_user -->|"compares faces"| node_face_comparison
node_cli_user -->|"runs command"| node_recognition_cli
node_cli_user -->|"runs command"| node_detection_cli
node_recognition_cli -->|"scans known faces"| node_known_people_scan
node_recognition_cli -->|"tests images"| node_unknown_image_test
node_known_people_scan -->|"loads images"| node_image_loading
node_known_people_scan -->|"encodes faces"| node_encoding
node_unknown_image_test -->|"loads image"| node_image_loading
node_unknown_image_test -->|"encodes faces"| node_encoding
node_unknown_image_test -->|"gets distances"| node_face_comparison
node_detection_cli -->|"processes images"| node_detection_image_test
node_detection_image_test -->|"loads image"| node_image_loading
node_detection_image_test -->|"gets locations"| node_face_detection
node_landmark_extraction -->|"locates faces"| node_face_detection
node_encoding -->|"uses landmarks"| node_landmark_extraction
node_face_detection -->|"dispatches detection"| node_dlib
node_landmark_extraction -->|"predicts landmarks"| node_dlib
node_face_detection -.->|"uses detector model"| node_face_models
node_landmark_extraction -->|"loads predictor model"| node_face_models

click node_image_loading "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py"
click node_face_detection "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py"
click node_landmark_extraction "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py"
click node_encoding "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py"
click node_face_comparison "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py"
click node_recognition_cli "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py"
click node_known_people_scan "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py"
click node_unknown_image_test "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py"
click node_detection_cli "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_detection_cli.py"
click node_detection_image_test "https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_detection_cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_recognition_cli,node_known_people_scan,node_unknown_image_test,node_detection_cli,node_detection_image_test,node_cli_user toneBlue
class node_image_loading,node_face_detection,node_landmark_extraction toneAmber
class node_encoding,node_face_comparison toneMint
class node_python_user,node_dlib,node_face_models toneIndigo
```

## Components

### User interfaces

- [Recognition CLI](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py): `face_recognition/face_recognition_cli.py`
- [Known face scan](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py): `face_recognition/face_recognition_cli.py`
- [Unknown image test](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_recognition_cli.py): `face_recognition/face_recognition_cli.py`
- [Detection CLI](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_detection_cli.py): `face_recognition/face_detection_cli.py`
- [Detection image test](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/face_detection_cli.py): `face_recognition/face_detection_cli.py`

### Face analysis

- [Image loading](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py): `face_recognition/api.py`
- [Face detection](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py): `face_recognition/api.py`
- [Landmark extraction](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py): `face_recognition/api.py`

### Face matching

- [Face encoding](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py): `face_recognition/api.py`
- [Face comparison](https://github.com/ageitgey/face_recognition/blob/master/face_recognition/api.py): `face_recognition/api.py`

### Other components

- **Python caller**
- **CLI user**
- **dlib**
- **Face models**

## Connections

- Python caller → Image loading: loads image (evidence: `README.md`)
- Python caller → Face detection: requests locations (evidence: `README.md`)
- Python caller → Landmark extraction: requests landmarks (evidence: `README.md`)
- Python caller → Face encoding: requests encodings (evidence: `README.md`)
- Python caller → Face comparison: compares faces (evidence: `README.md`)
- CLI user → Recognition CLI: runs command (evidence: `README.md`)
- CLI user → Detection CLI: runs command (evidence: `README.md`)
- Recognition CLI → Known face scan: scans known faces (evidence: `face_recognition/face_recognition_cli.py`)
- Recognition CLI → Unknown image test: tests images (evidence: `face_recognition/face_recognition_cli.py`)
- Known face scan → Image loading: loads images (evidence: `face_recognition/face_recognition_cli.py`)
- Known face scan → Face encoding: encodes faces (evidence: `face_recognition/face_recognition_cli.py`)
- Unknown image test → Image loading: loads image (evidence: `face_recognition/face_recognition_cli.py`)
- Unknown image test → Face encoding: encodes faces (evidence: `face_recognition/face_recognition_cli.py`)
- Unknown image test → Face comparison: gets distances (evidence: `face_recognition/face_recognition_cli.py`)
- Detection CLI → Detection image test: processes images (evidence: `face_recognition/face_detection_cli.py`)
- Detection image test → Image loading: loads image (evidence: `face_recognition/face_detection_cli.py`)
- Detection image test → Face detection: gets locations (evidence: `face_recognition/face_detection_cli.py`)
- Landmark extraction → Face detection: locates faces (evidence: `face_recognition/api.py`)
- Face encoding → Landmark extraction: uses landmarks (evidence: `face_recognition/api.py`)
- Face detection → dlib: dispatches detection (evidence: `face_recognition/api.py`)
- Landmark extraction → dlib: predicts landmarks (evidence: `face_recognition/api.py`)
- Face detection → Face models: uses detector model
- Landmark extraction → Face models: loads predictor model (evidence: `face_recognition/api.py`)
