OpenFace: face recognition with FaceNet embeddings, installed from the repo

What OpenFace actually solves, and for whom

OpenFace answers a narrow question: given a photograph of a face, produce a numeric representation that lets you compare it to another face. The README describes the project as free and open source face recognition with deep neural networks, and the repository is organised around that single job. The batch-represent directory generates representations from a batch of images, and the openface directory holds the Python library code that wraps the model. If you are a researcher who wants to reproduce a FaceNet-style pipeline, inspect the training scripts under training, or run the LFW accuracy evaluation under evaluation, this is the shape of project you want. If you are building a product that must identify people in a live video feed with a support contract, the repository layout tells you something else: there is a demos/web directory and a classifier_webcam.py demo, but those are demonstrations, not a service. The distinction matters because the README leads with a research framing and cites a CMU tech report from 2016, not an operations guide.

How the embedding pipeline is wired

The mechanism is a feed-forward network trained to map a face image to a vector, then compared by distance. The setup.py description names the network directly: face recognition with Google's FaceNet deep neural network. Torch is the original backend, which is why the primary language listed for the repository is Lua and why package_data in setup.py ships *.lua files alongside the Python package. The Dockerfile shows the runtime dependencies the project expects: opencv-python and dlib in requirements.txt, plus system libraries libatlas-base-dev, libboost-all-dev, libopenblas-dev and liblapack-dev. The data flow is visible in the directory names. Images go into batch-represent, which calls into the openface Python library, which loads the model from models and emits representations. From there, demos/classifier.py trains a classifier on top of those representations, and demos/compare.py compares two images directly. The models directory is described as the model directory for openface and third party libraries, and the Dockerfile runs ./models/get-models.sh before installing the Python package, which tells you the model weights are fetched rather than committed. That is a real architectural constraint: a fresh clone without network access has no model.

Installing OpenFace with Docker, and running the web demo

The Dockerfile is the most complete installation path in the repository, because it pins the base image and installs the system libraries that dlib and OpenCV need. It starts from an NVIDIA CUDA image, so the build expects a CUDA-capable environment. The final lines install the model weights, the Python requirements and the package itself.

FROM nvidia/cuda:11.8.0-cudnn8-devel-ubuntu22.04
ADD . /root/openface
WORKDIR /root/openface
RUN ./models/get-models.sh && \
    python3 -m pip install -r requirements.txt && \
    python3 -m pip install .
EXPOSE 8000 9000

The two exposed ports, 8000 and 9000, are the ones the Dockerfile declares. Note the commented lines at the bottom of the file: the demos/web requirements and the training requirements are disabled by default, so a plain build gives you the library and the models, not the web demo or the training scripts. To get those you would install the corresponding requirements files yourself.

If you prefer a local install, the repository also ships a setup.py and a requirements.txt. The requirements file pins numpy below version 2, which is the detail most likely to bite you first.

python3 -m pip install -r requirements.txt
python3 -m pip install .

After that, the demos are the first real use. demos/compare.py compares two images, and demos/classifier.py trains and uses classifiers. The README points at a gist for the example directory structure that batch-represent expects, which is worth reading before you feed it a folder of images, because the script is organised around a specific layout rather than arbitrary file names.

Where OpenFace stops being the right tool

The dependency list is the clearest limitation. requirements.txt pins numpy<2, which means any environment already built on numpy 2.x will conflict. The Dockerfile targets an Ubuntu 22.04 base with CUDA 11.8, so newer CUDA drivers and newer distributions are outside what the repository configures. The Torch dependency is the original Torch lineage, not PyTorch, and the Lua files shipped as package data are a reminder that the training path is not a modern Python training loop. The README does not document rollback, does not describe a deprecation policy, and does not offer a migration path away from the Torch backend. There is also a licensing boundary worth reading carefully: the README states that source code and trained Torch and Python model files are Apache 2.0, but lists modified third-party portions under MIT, BSD and CC0, including a 68-point face landmark detector from dlib-models under CC0. If your use case requires a single uniform licence across every file you ship, you need to audit those included portions rather than assume the repository is uniformly Apache-2.0. Finally, face recognition is a regulated activity in several jurisdictions. Nothing in this repository addresses consent, retention or biometric privacy law, and the README does not claim to.

OpenFace against MediaPipe and DeepFace

The two comparisons people search for are against MediaPipe and DeepFace, and the difference is in what each project is for. OpenFace is a recognition pipeline: it produces embeddings from a FaceNet model and lets you train a classifier on top of them, with evaluation and training scripts included in the same repository. MediaPipe, by contrast, is a framework for on-device perception pipelines, with face detection and landmark models that run in a graph; it is not organised around producing a comparable identity embedding you then classify. DeepFace is closer in intent, a Python library that wraps several recognition models behind one interface, but that wrapping is the difference: it abstracts the model choice, while OpenFace ships one lineage of models and the scripts to train and evaluate them. If you want to swap recognisers and compare them behind a common API, the abstraction is the point. If you want to read the training code and reproduce the evaluation, OpenFace's transparency is the point. Neither is a substitute for the other.

Maintenance, releases and the cost of upgrading

The release history is uneven. 0.2.0 and 0.2.1 both landed in early 2016, and then the next tagged release, 0.2.2, is dated 2024-10-04 and carries the tag lua_final. The last push to the default branch was on 2026-07-18. The tag name is the useful signal here: it suggests the Lua side of the project has reached a terminal state, and setup.py reports a version of 0.3.2, which does not match any of the listed release tags. That mismatch between the packaged version and the release list is the kind of thing you should resolve before pinning a dependency, because a version specifier aimed at a tag may not correspond to what pip resolves. The README does not document an upgrade procedure between these versions. Practically, the upgrade cost is dominated by the environment rather than the code: moving to a newer Ubuntu base means rebuilding dlib and OpenCV against a newer toolchain, and moving past numpy 2 means either patching the requirement or isolating OpenFace in its own environment. Budget for that before you plan a version bump.

What to check before you commit to it

Start with the models step. The Dockerfile runs ./models/get-models.sh as part of the build, so the question of whether that script succeeds in your network environment is the first gate. Then confirm your Python version against the Ubuntu 22.04 base in the Dockerfile, and confirm that dlib and opencv-python build or install cleanly on your platform; these are the two dependencies most likely to fail on a fresh machine. If you intend to use the web demo, remember it is commented out of the Dockerfile and needs demos/web/requirements.txt installed separately. If you intend to train, note that training/requirements.txt is commented out too. The demos/compare.py script is the cheapest end-to-end check: if it produces a comparison, the model weights, the library and the image loading path are all working. The README points to a Gitter chat and a Google group for installation issues, and states that bugs belong on the issue tracker, which is where you would go if the models script or the dlib build fails.

Editorial conclusion

Adopt OpenFace if you need an open, inspectable FaceNet pipeline you can train and evaluate yourself, and if you can live with a Torch-era stack pinned to numpy<2. Do not adopt it if you need a maintained, packaged identity API with vendor support; the last push was on 2026-07-18, but the project still ships a 2016 tech report and the README does not document rollback, deprecation policy or a migration path. Verify first that your Python and CUDA versions satisfy the Dockerfile base image, that dlib builds against your compiler toolchain, and that the models directory is populated by models/get-models.sh before you run any demo.

Frequently asked questions

Official sources

1. cmusatyalab/openface on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases