InsightFace Python Library

0.7.3 · active · verified Sun Apr 12

InsightFace is an open-source 2D & 3D deep face analysis toolbox for tasks like face recognition, detection, and alignment, with capabilities extending to face swapping and anti-spoofing. It provides state-of-the-art models optimized for both training and deployment. The library primarily uses ONNX Runtime as its inference backend. The current version is 0.7.3, and it maintains an active development and maintenance cadence with frequent updates and community support.

Warnings

breaking Backend Change from MXNet to ONNX Runtime: `insightface` versions 0.2 and above transitioned from MXNet to ONNX Runtime as the default inference backend. Older code expecting MXNet or models in MXNet format will not work directly with newer versions.
Fix: Ensure your environment has `onnxruntime` or `onnxruntime-gpu` installed. Convert any custom MXNet models to ONNX format.
gotcha GPU (CUDA/cuDNN) Compatibility for `onnxruntime-gpu`: Installing `onnxruntime-gpu` requires precise compatibility between the ONNX Runtime wheel, your installed CUDA toolkit, and cuDNN versions. Mismatches frequently lead to `onnxruntime` silently falling back to CPU or installation failures.
Fix: Carefully consult ONNX Runtime's official documentation for CUDA/cuDNN version requirements. Consider using `pip install "onnxruntime-gpu[cuda,cudnn]"` in a clean virtual environment to auto-manage dependencies, or ensure your local CUDA setup matches.
gotcha Pretrained Model License Restrictions: The pretrained models provided and auto-downloaded by the `insightface` library are strictly for non-commercial research purposes only. Commercial use of these models, especially certain series like `inswapper`, requires separate licensing.
Fix: Review the license terms carefully before deploying in commercial applications. For commercial use, consider training your own models or contacting `contact@insightface.ai` for specific model licenses.
gotcha Python Build Tool Requirements for Installation: Installation (especially for specific versions or environments, e.g., on Windows or Linux without common build tools) can fail with "Failed building wheel" errors. This typically indicates missing C++ build tools or Python development headers.
Fix: On Windows, install the "Desktop development with C++" workload via Visual Studio Installer. On Debian/Ubuntu Linux, install `python3-dev` (e.g., `sudo apt-get install python3-dev build-essential`).
gotcha NumPy Version Conflict with ONNX: Recent `insightface` versions and their `onnx` dependency might have compatibility issues with `NumPy 2.x`. It's recommended to stick to `NumPy 1.x` for stability.
Fix: Explicitly install `NumPy` with a version constraint: `pip install "numpy<2"`.
gotcha Model Download Failures in Restricted Regions: Some models are hosted on Google Drive, which can be inaccessible in certain geographical regions (e.g., China), leading to download failures during `FaceAnalysis` initialization.
Fix: Manually download the required model packs (often available on GitHub releases) and place them in `~/.insightface/models/` as per the documentation, or use a VPN.

Install

pip install insightface Basic Installation
pip install insightface onnxruntime opencv-python "numpy<2" Recommended CPU Installation
pip install insightface onnxruntime-gpu opencv-python "numpy<2" Recommended GPU Installation (requires CUDA/cuDNN)

Imports

FaceAnalysis

from insightface.app import FaceAnalysis

get_image
```
from insightface.data import get_image
```

Quickstart

This quickstart demonstrates how to initialize the `FaceAnalysis` application, prepare it with execution providers (preferring CUDA if available), load a bundled sample image, perform face detection and analysis, and draw the results on the image. It also prints basic information about the first detected face.

import cv2
import numpy as np
import insightface
from insightface.app import FaceAnalysis
from insightface.data import get_image as ins_get_image

# Initialize FaceAnalysis app with desired providers (e.g., CUDA or CPU)
# Ensure onnxruntime-gpu is installed for CUDAExecutionProvider
app = FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
app.prepare(ctx_id=0, det_size=(640, 640))

# Load a sample image
img = ins_get_image('t1') # 't1' is a sample image bundled with the library

# Perform face detection and analysis
faces = app.get(img)

# Draw results on the image
rimg = app.draw_on(img, faces)

# Display or save the output image
# cv2.imshow("InsightFace Demo", rimg)
# cv2.waitKey(0)
# cv2.destroyAllWindows()
cv2.imwrite("./t1_output.jpg", rimg)
print(f"Detected {len(faces)} face(s). Output saved to t1_output.jpg")

if faces:
    face = faces[0]
    print(f"Face 0: Bounding Box: {face.bbox}, Landmark: {face.landmark}")
    if face.embedding is not None:
        print(f"Face 0: Embedding shape: {face.embedding.shape}")
    if face.gender is not None:
        print(f"Face 0: Gender: {face.gender}, Age: {face.age}")

view raw JSON →