Skip to main content

Detector 2D or 3D face landmarks from Python

Project description

Face Recognition

Detect facial landmarks from Python using the world's most accurate face alignment network, capable of detecting points in both 2D and 3D coordinates.

Build using FAN's state-of-the-art deep learning based face alignment method.

Note: The lua version is available here.

For numerical evaluations it is highly recommended to use the lua version which uses indentical models with the ones evaluated in the paper. More models will be added soon.

License Build Status Anaconda-Server Badge


Detect 2D facial landmarks in pictures

import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType._2D, flip_input=False)

input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)

Detect 3D facial landmarks in pictures

import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType._3D, flip_input=False)

input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)

Process an entire directory in one go

import face_alignment
from skimage import io

fa = face_alignment.FaceAlignment(face_alignment.LandmarksType._2D, flip_input=False)

preds = fa.get_landmarks_from_directory('../test/assets/')

Detect the landmarks using a specific face detector.

By default the package will use the SFD face detector. However the users can alternatively use dlib or pre-existing ground truth bounding boxes.

import face_alignment

# sfd for SFD, dlib for Dlib and folder for existing bounding boxes.
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType._2D, face_detector='sfd')

Running on CPU/GPU

In order to specify the device (GPU or CPU) on which the code will run one can explicitly pass the device flag:

import face_alignment

# cuda for CUDA
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType._2D, device='cpu')

Please also see the examples folder



  • Python 3.5+ or Python 2.7 (it may work with other versions too)
  • Linux, Windows or macOS
  • pytorch (>=0.4)

While not required, for optimal performance(especially for the detector) it is highly recommended to run the code using a CUDA enabled GPU.


conda install -c 1adrianb face_alignment

From source

Install pytorch and pytorch dependencies. Instructions taken from pytorch readme. For a more updated version check the framework github page.

On Linux

export CMAKE_PREFIX_PATH="$(dirname $(which conda))/../" # [anaconda root directory]

# Install basic dependencies
conda install numpy pyyaml mkl setuptools cmake gcc cffi

# Add LAPACK support for the GPU
conda install -c soumith magma-cuda80 # or magma-cuda75 if CUDA 7.5


export CMAKE_PREFIX_PATH=[anaconda root directory]
conda install numpy pyyaml setuptools cmake cffi

Get the PyTorch source

git clone --recursive

Install PyTorch

On Linux

python install


MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python install

Get the Face Alignment source code

git clone

Install the Face Alignment lib

pip install -r requirements.txt
python install

Docker image

A Dockerfile is provided to build images with cuda support and cudnn v5. For more instructions about running and building a docker image check the orginal Docker documentation.

docker build -t face-alignment .

How does it work?

While here the work is presented as a black-box, if you want to know more about the intrisecs of the method please check the original paper either on arxiv or my webpage.


All contributions are welcomed. If you encounter any issue (including examples of images where it fails) feel free to open an issue.


  title={How far are we from solving the 2D \& 3D Face Alignment problem? (and a dataset of 230,000 3D facial landmarks)},
  author={Bulat, Adrian and Tzimiropoulos, Georgios},
  booktitle={International Conference on Computer Vision},

For citing dlib, pytorch or any other packages used here please check the original page of their respective authors.


  • To the pytorch team for providing such an awesome deeplearning framework
  • To my supervisor for his patience and suggestions.
  • To all other python developers that made available the rest of the packages used in this repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for face-alignment, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size face_alignment-1.0.0-py2.py3-none-any.whl (22.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size face_alignment-1.0.0-py3.6.egg (47.2 kB) File type Egg Python version 3.6 Upload date Hashes View
Filename, size face_alignment-1.0.0.tar.gz (20.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page