face_alignment

1.5.0 verified Mon Apr 27 auth: no python

Face alignment is a Python library for detecting 2D or 3D face landmarks from images. Current version 1.5.0 supports multiple detection models (SFD, BlazeFace, etc.) and landmark models (2D and 3D). Release cadence is irregular, with major updates every few months.

pip install face-alignment

Common errors

error ModuleNotFoundError: No module named 'face_alignment' ↓

cause Package not installed or installed with wrong name.

fix

pip install face-alignment

error TypeError: 'NoneType' object is not iterable ↓

cause get_landmarks returned None because no face detected.

fix

Check: if preds is not None: ...

error RuntimeError: Model not found. Please download the model first. ↓

cause Missing model weights; network issue prevented download.

fix

Run once with internet, or manually download from torch.hub.

error AttributeError: module 'face_alignment' has no attribute 'FaceAlignment' ↓

cause Wrong import statement: import face_alignment instead of from face_alignment import FaceAlignment.

fix

Use: from face_alignment import FaceAlignment

error ValueError: Cannot load model with given network size ↓

cause Incorrect NetworkSize argument.

fix

Use NetworkSize.LARGE or NetworkSize.LARGE2 (4GB+ VRAM) as appropriate.

Warnings

breaking In v1.5.0, support for Python <3.8 and PyTorch <1.12 is dropped. Older installations may fail. ↓

fix Upgrade Python to 3.8+ and PyTorch to 1.12+.

breaking The package no longer ships with bundled model weights; models are downloaded via torch.hub on first use. This requires an internet connection. ↓

fix Ensure internet access or pre-download models by running once.

gotcha FaceAlignment.get_landmarks() returns None if no face is detected, not an empty list. Iterating over None will cause TypeError. ↓

fix Always check: if preds is not None: ...

deprecated The conda package is no longer maintained. Use pip instead. ↓

fix Install via pip install face-alignment.

gotcha The library expects images in BGR format (OpenCV default), but the detection model may expect RGB. Inconsistent behavior across versions. ↓

fix If landmarks are inaccurate, convert image: img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB).

Install

pip install face-alignment --no-deps

Imports

FaceAlignment
wrong
```
import face_alignment
```
correct
```
from face_alignment import FaceAlignment
```
The class is not the module; must import explicitly.

LandmarksType

from face_alignment import LandmarksType

NetworkSize
```
from face_alignment import NetworkSize
```

Quickstart

Load an image, run face alignment, and print 2D landmarks.

import cv2
from face_alignment import FaceAlignment, LandmarksType, NetworkSize

fa = FaceAlignment(LandmarksType.TWO_D, network_size=NetworkSize.LARGE)
img = cv2.imread('input.jpg')
preds = fa.get_landmarks(img)
print(preds)