Registry / ai-ml / face-alignment

face-alignment

library1.5.0pypypi✓ verified 86d ago

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.

ai-ml

pip install face-alignment

github ↗package ↗

INSTALL

IMPORT

SIG · FACE-ALIGNMENT

face-alignment

ai-mlpythonv1.5.0

Install

39.1s avg

Import

—

Disk

5427MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

1/2 runs

✓ 44.5s

py 3.11

1/2 runs

✓ 41.3s

py 3.12

1/2 runs

✓ 36.1s

py 3.13

1/2 runs

✓ 34.5s

py 3.9

1/2 runs

5427MB installed

● package 5427MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FaceAlignment

✓ from face_alignment import FaceAlignment

✗ import face_alignment

The class is not the module; must import explicitly.

LandmarksType

✓ from face_alignment import LandmarksType

NetworkSize

✓ from face_alignment import NetworkSize

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)

Debug

Known issues

breakingIn 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+.

affects: >=1.5.0

breakingThe 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.

affects: >=1.5.0

gotchaFaceAlignment.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: ...

affects: all

deprecatedThe conda package is no longer maintained. Use pip instead.

fix

Install via pip install face-alignment.

affects: >=1.5.0

gotchaThe 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).

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'face_alignment'

Package not installed or installed with wrong name.

fix

pip install face-alignment

TypeError: 'NoneType' object is not iterable

get_landmarks returned None because no face detected.

fix

Check: if preds is not None: ...

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

Missing model weights; network issue prevented download.

fix

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

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

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

fix

Use: from face_alignment import FaceAlignment

ValueError: Cannot load model with given network size

Incorrect NetworkSize argument.

fix

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

Upgrade

Version history

1.5.0latest on PyPI · released Apr 6, 2026

Audit

Dependencies

torchrequiredDeep learning framework for model inference.

numpyrequiredArray operations.

opencv-pythonrequiredImage loading and processing.

scikit-imagerequiredImage transformation utilities.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/1adrianb/face-alignment ↗

packagehttps://pypi.org/project/face-alignment/ ↗