$ show ageitgey/face_recognition
face_recognition is a Python library and CLI toolkit that wraps dlib's deep-learning-based face recognition models behind a simple, high-level API. It provides functions to detect face locations (HOG or CNN-based), extract 68-point or 5-point facial landmarks, compute 128-dimensional face encodings, and compare faces via Euclidean distance. The package ships two Click-based CLI entry points — `face_recognition` for batch identification against a known-people folder and `face_detection` for locating faces in images — both supporting multiprocessing and tunable tolerance/upsample parameters. The core logic lives in `face_recognition/api.py`, which is essentially a thin, well-abstracted wrapper around dlib detectors, shape predictors, and the ResNet face encoder, with coordinate conversion helpers to keep the public API in (top, right, bottom, left) tuple form. The repo also includes a large examples directory (webcam recognition, KNN/SVM classifiers, blink detection, batch GPU inference, Flask web service, Raspberry Pi integration) and multi-stage Docker builds for CPU and GPU deployment. Last tagged release is 1.4.0 (2020); the final commit on master dates to mid-2026 but the project shows little active development and many open issues, placing it in 'stale' maintenance status. Technical drift is medium: the codebase still references Python 2.7 in places, pins older dlib versions in some Dockerfiles, and has CI only through 3.10, while the ecosystem has moved to Python 3.12+ and dlib 19.24+. The API wrapper itself is clean and reusable, but the CLI modules and examples are too tightly coupled to the library and filesystem assumptions to be extracted as standalone components.
The LLM identified 4 files worth highlighting for reuse:
A clean facade over dlib's face detection, landmark prediction, and face-encoding models. It standardizes all outputs to (top, right, bottom, left) tuples, provides both HOG and CNN detectors, supports 5-point and 68-point landmark models, and includes a vectorized `face_distance` using numpy. The `batch_face_locations` function demonstrates GPU-accelerated batch inference with dlib's CNN detector. This module is the genuinely reusable core — an engineer could lift it into another vision project as a drop-in face-analysis utility, provided dlib and the face_recognition_models package are available.
Implements a production-style Click CLI that scans a folder of known people, computes their face encodings once, then classifies faces in unknown images or folders. Notable patterns: automatic image-file filtering by extension, graceful handling of images with zero or multiple faces, optional image downscaling for performance, and a multiprocessing pool with macOS forkserver workaround. The `scan_known_people` and `process_images_in_process_pool` functions illustrate a reusable pattern for parallelizing CPU-bound batch image tasks that could be adapted to other domains.
Companion CLI for face detection that outputs pixel coordinates. Shares the same multiprocessing and image-folder scanning patterns as the recognition CLI, making it a good reference for building parallelized, Click-based image-processing command-line tools. The model-selection option (HOG vs CNN) and upsample parameter expose dlib's detection knobs in a user-friendly way.
A well-structured multi-stage Dockerfile that compiles dlib from source with static linking in a builder stage, then copies only the venv and required shared libraries into a slim runtime image. This pattern produces a relatively small, self-contained image suitable for deployment. The technique of copying individual .so files rather than the full build environment is a useful reference for deploying C-extension-heavy Python packages in containers.