The following instructions are for Linux and OSX only. Please contribute modifications and build instructions if you are interested in running this on other operating systems.

Warning for architectures other than 64-bit x86

See #42.

Check out git submodules

Clone with --recursive or run git submodule init && git submodule update after checking out.

With Docker

This repo can be used as a container with Docker for CPU mode. Depending on your Docker configuration, you may need to run the docker commands as root.

Automated Docker Build

The quickest way to getting started is to use our pre-built automated Docker build, which is available from bamos/openface. This does not require or use a locally checked out copy of OpenFace. To use on your images, share a directory between your host and the Docker container.

docker pull bamos/openface
docker run -p 9000:9000 -p 8000:8000 -t -i bamos/openface /bin/bash
cd /root/openface
./demos/ images/examples/{lennon*,clapton*}
./demos/ infer models/openface/celeb-classifier.nn4.small2.v1.pkl ./images/examples/carell.jpg

Building a Docker Container

This builds a Docker container from a locally checked out copy of OpenFace, which will take about 2 hours on a modern machine. Be sure you have checked out the git submodules. Run the following commands from the openface directory.

docker build -t openface .
docker run -p 9000:9000 -p 8000:8000 -t -i openface /bin/bash
cd /root/openface
./demos/ images/examples/{lennon*,clapton*}
./demos/ infer models/openface/celeb-classifier.nn4.small2.v1.pkl ./images/examples/carell.jpg

Docker in OSX

In OSX, follow the Docker Mac OSX Installation Guide and start a docker machine and connect your shell to it before trying to build the container. In the simplest case, this can be done with:

docker-machine create --driver virtualbox --virtualbox-memory 4096 default
eval $(docker-machine env default)

Docker memory issues in OSX

Some users have reported the following silent Torch/Lua failure when running batch-represent caused by an out of memory issue.

/root/torch/install/bin/luajit: /openface/batch-represent/dataset.lua:191: attempt to perform arithmetic on a nil value

If you're experiencing this, make sure you have created a Docker machine with at least 4GB of memory with --virtualbox-memory 4096.

By hand

Be sure you have checked out the submodules and downloaded the models as described above. See the Dockerfile as a reference.

This project uses python2 because of the opencv and dlib dependencies. Install the packages the Dockerfile uses with your package manager. With pip2, install numpy, pandas, scipy, scikit-learn, and scikit-image.

Next, manually install the following.


Download OpenCV 2.4.11 and follow their build instructions.


dlib can be installed from pypi or built manually and depends on boost libraries. Building dlib manually with AVX support provides higher performance.

To build manually, download dlib v18.16, then run the following commands. For the final command, make sure the directory is in your default Python path, which can be found with sys.path in a Python interpreter. In OSX, use site-packages instead of dist-packages.

mkdir -p ~/src
cd ~/src
tar xf dlib-18.16.tar.bz2
cd dlib-18.16/python_examples
mkdir build
cd build
cmake ../../tools/python
cmake --build . --config Release
sudo cp /usr/local/lib/python2.7/dist-packages

At this point, you should be able to start your python2 interpreter and successfully run import cv2; import dlib.

In OSX, you may get a Fatal Python error: PyThreadState_Get: no current thread. You may be able to resolve by rebuilding python and boost-python as reported in #21, but please file a new issue with us or dlib if you are unable to resolve this.


Install Torch from the instructions on their website. At this point, the command-line program th should be available in your shell. Install the dependencies with luarocks install $NAME, where $NAME is as listed below.

These can all be installed with:

for NAME in dpnn nn optim optnet csvigo cutorch cunn fblualib torchx tds; do luarocks install $NAME; done


In OSX, install findutils and coreutils with Brew or MacPorts for the prefixed GNU variants gfind and gwc. These are required for the commands to be compatible with the Linux defaults of these commands.

From the root OpenFace directory, install the Python dependencies with sudo python2 install.

Run models/ to download pre-trained OpenFace models on the combined CASIA-WebFace and FaceScrub database. This also downloads dlib's pre-trained model for face landmark detection. This will incur about 200MB of network traffic.