# face_recognition needs dlib before pip, and its newest tag is from 2018

> face_recognition wraps dlib's deep learning face recognition in a small Python API and two command line tools. The install is a three step affair, Windows is unsupported, the Jetson path fails silently, and the two dependency files in the repository disagree with each other.

**ageitgey/face_recognition** — The world's simplest facial recognition api for Python and the command line.

- Repository: https://github.com/ageitgey/face_recognition
- Stars: 56,782 · Forks: 13,683
- Language: Python
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/ageitgey-face-recognition

## dlib has to exist before the library does

The install is three steps and the interesting one is first. On macOS and Linux you are told to make sure you have dlib already installed with Python bindings, with a link to a walkthrough for building dlib from source on macOS or Ubuntu. Then you make sure cmake is installed, which the project shows as a brew install on macOS. Then, and only then, you install the module from PyPI using pip3, or pip2 for Python 2:
```bash
pip3 install face_recognition
```
What the one-line pip command cannot do is bring its own dependency. The recognition work happens inside dlib, so this install is a thin wrapper that assumes a compiled library with Python bindings is already on your machine. A reader who jumps straight to the pip line on a clean machine will not get a working detector, and the error will point at a missing shared library rather than at the step they skipped. The stated requirements are Python 3.3 or later or Python 2.7, on macOS or Linux.

## The packaging metadata lives in setup.py, not pyproject.toml

The build configuration is older than it looks. pyproject.toml contains only a build-system table requiring setuptools and wheel, with no project metadata at all, so the name, version, dependencies, entry points, and classifiers all live in setup.py, with setup.cfg alongside it. That file declares the name as face_recognition, the version as 1.4.0, and the license as MIT, and it reads two files off disk, concatenating README.rst and HISTORY.rst into the long description. The model weights ship as package data matching models/*.dat, and the two commands are declared as console_scripts entry points pointing at face_recognition_cli and face_detection_cli. What this arrangement cannot do is move to current packaging conventions without moving the metadata, since there is no project table for a modern build backend to read. The development status classifier is 4 - Beta, which is the project's own label for itself.

## Two dependency files disagree on dlib and on scipy

The repository declares its dependencies twice, and the two declarations are not the same. The install requirements in setup.py are face_recognition_models at 0.3.0 or newer, Click at 6.0 or newer, dlib at 19.7 or newer, numpy, and Pillow. The requirements.txt file lists face_recognition_models, Click at 6.0 or newer, dlib at 19.3.0 or newer, numpy, Pillow, and scipy at 0.17.0 or newer. So the dlib floor differs between the two, and scipy appears in only one of them. What this cannot do is give you one answer to what you are installing. A plain pip install follows the setup.py path and gets dlib 19.7 with no scipy, while installing from requirements.txt accepts an older dlib and pulls scipy in. The test story is similarly dated, with test_requirements naming tox and flake8, a test_suite of tests, and a tox.ini at the root.

## The Jetson path fails silently, and the GPU compose lines are commented out

The board-specific instructions are the sharpest warning in the project, and it is about silence rather than a crash. There is a bug in the CUDA libraries on the Jetson Nano that will cause this library to fail silently if you do not follow the article carefully, which means commenting out a line in dlib and recompiling it. What that cannot do is produce an error you can debug. A silent failure looks exactly like a working script that finds nothing, so a reader who skips the recompile is likely to conclude that the library does not detect faces rather than that the library never loaded, and will go looking in the wrong place. The same pattern shows up in the container path. docker-compose.yml builds one service, mounts the repository into it, and overrides the command with a single example script, while the lines selecting Dockerfile.gpu and the nvidia runtime both sit commented out with a note that uncommenting them requires Nvidia-Docker.

## Windows works only through a community guide in an issue thread

The stated requirement is macOS or Linux, with a parenthetical that Windows is not officially supported but might work. The Windows section offers no instructions from the project. It points at a guide posted by a user in the issue tracker, a Windows 10 installation guide covering dlib plus face_recognition, and notes that helpful users have posted instructions there. What that arrangement cannot do is keep working for you. The supported paths, the Raspberry Pi instructions, the Jetson article, a FreeBSD package install, and a pre-configured virtual machine image, are maintained by the project, while the Windows route is a third-party walkthrough living in a discussion that can drift away from whatever dlib is current. The same pattern runs through the documentation set, since the project ships Simplified Chinese, Korean, and Japanese readmes as separate files, and its only online demo is described as a user-contributed shared notebook that is not officially supported.

## Two command line tools, one tolerance knob, and no default worth trusting

Installing the package gives you two programs. The face_recognition command takes a folder of people you already know, with one image per person and filenames naming who is in the picture, plus a second folder of images to identify:
```bash
$ face_recognition ./pictures_of_people_i_know/ ./unknown_pictures/
```
It prints one comma-separated line per face, the filename and the name it found, and a face that matched nobody comes back as unknown_person. The face_detection command does the locating instead, printing the top, right, bottom, and left pixel coordinates of each face it finds. The one tuning control named is a tolerance parameter, and the guidance is that if you are getting multiple matches for the same person, the people in your photos look similar and a lower tolerance makes comparisons stricter. What that cannot do is be neutral. One knob sets your false accepts against your false rejects, and the folder-of-known-faces format also puts a ceiling on quality, since a bad reference photo becomes a face nobody matches.

## A 99.38 percent LFW score is not a statement about your deployment

The library is built on dlib's face recognition using deep learning, and the model has an accuracy of 99.38 percent on the Labeled Faces in the Wild benchmark, with the LFW paper linked for the details. What that figure cannot do is transfer to the conditions you care about. LFW is one benchmark with its own subjects, capture conditions, and evaluation protocol, and a score on it says nothing about your camera, your lighting, or faces seen at an angle or at distance. There is no operating point hiding inside that number either. The library compares against a tolerance, and where you set that tolerance decides how readily a lookalike is accepted as a known person. The benchmark tells you the encoder is strong. It does not tell you the threshold you should ship, and quoting the accuracy figure in a design review is the wrong move, because the number that matters is the false accept rate at the tolerance your data actually produces.

## setup.py reads 1.4.0 while the newest tag is v1.2.2 from 2018

The version trail has come apart. setup.py declares version 1.4.0, and its classifiers list Python 3 through 3.9. The tagged releases are v1.2.2 from 2018-04-02 and v0.1.12 from 2017-04-13, and the repository was last pushed to on 2026-06-25. What this cannot do is give you a tag that matches what pip installs. There is no v1.4.0 release, so anyone pinning from the releases page gets code older than what the package metadata claims, and anyone trusting the metadata gets code that is not tied to a reviewable tag. The classifier list is the second problem: it stops at Python 3.9 while the README asks for Python 3.3 or later, so a reader on a current interpreter sits outside the officially enumerated range even though nothing suggests it should be. If your build pins an interpreter by classifier, you are pinning against a list frozen years ago.

## The classifier lives in the examples, not in the library

The library stops at a vector and a distance, and leaves the decision to you. The Python API produces an encoding for a face and compares encodings, and everything past that is demonstrated rather than packaged. The examples directory carries a KNN classifier script and an SVM classifier script side by side, along with webcam, faster webcam, and multiprocessing webcam variants, video file and IP camera scripts, a batch face finder, a plain picture finder alongside a CNN picture finder, blink detection, blurring faces, a digital makeup example, a face distance script, a benchmark, and a script that draws boxes on detected faces, plus ipynb_examples and knn_examples directories. What this cannot do is decide for you what counts as a match. Choosing KNN over an SVM, deciding how many neighbours, and setting the tolerance are all choices you make with code the project shows you rather than code the project owns, and every one of them changes your false accept rate.

## Conclusion

face_recognition suits a developer who wants face detection and identification from Python or a shell with dlib doing the heavy work, and who is willing to build dlib first. It does not suit a Windows-only team, an edge deployment on Jetson hardware without reading the article first, or anyone who needs a clean release trail, because the newest tag is from 2018 while the package version reads 1.4.0. Before you commit, confirm your Python version is one the classifiers cover, settle which dependency file you are installing from, and set your tolerance deliberately rather than inheriting whatever default you get.

## FAQ

### how to install face_recognition in python

You must install dlib with Python bindings first, then cmake, then run pip3 install face_recognition. The stated requirements are Python 3.3 or later or Python 2.7, on macOS or Linux, since the recognition work happens inside dlib rather than in this package.

### how to use face_recognition

From Python you can call face_locations to find faces, face_landmarks to get eyes, nose, mouth, and chin positions, face_encodings to produce a comparison vector, and compare_faces to match them. Installing the package also gives you the face_recognition and face_detection commands, plus Dockerfile and Dockerfile.gpu for container builds.

### How to find a person by photo with face_recognition?

Put one image per known person in a folder, with filenames naming who appears, put the images to identify in a second folder, then run face_recognition with both paths. It prints one comma-separated line per face, and a face that matched nobody in the known folder is reported as unknown_person.

## Sources

- [Official README](https://github.com/ageitgey/face_recognition#readme)
- [Project repository](https://github.com/ageitgey/face_recognition)
- [Release notes](https://github.com/ageitgey/face_recognition/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ageitgey-face-recognition