Registry / ai-ml / insightface

insightface

JSON →
library1.0.1pypypi✓ verified 21d ago

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.

pip install insightface
INSTALL
IMPORT
SIG · INSIGHTFACE
I
insightface
ai-mlpythonv1.0.1
Install
23.3s avg
Import
Disk
794MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.1 · 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
✕ build_error
✓ 27.27s
py 3.11
✕ build_error
✓ 17.97s
py 3.12
✕ build_error
✓ 17.83s
py 3.13
✕ build_error
1/3 runs
py 3.9
✕ build_error
✓ 30.03s
794MB installed
● package 794MB
Code
Verified usage

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

FaceAnalysis
from insightface.app import FaceAnalysis
pip install insightface onnxruntime opencv-python "numpy<2" — all four required
get_image
from insightface.data import get_image

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}")
inswapper --version
Debug
Known issues
breakingBackend 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.
affects: insightface>=0.2
gotchaGPU (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.
affects: insightface>=0.2 (when using GPU)
gotchaPretrained 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.
affects: All versions
gotchaPython 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`).
affects: All versions, particularly during `pip install`.
gotchaNumPy 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"`.
affects: Recent insightface versions (0.7.x) with onnx/onnxruntime
gotchaModel 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.
affects: All versions that auto-download models from Google Drive.
Errors
Common errors & fixes
[ONNXRuntimeError] : 1 : FAIL : Error loading 'onnxruntime_providers_cuda.dll' which depends on 'cudnn64_9.dll' which is missing.
cuDNN version mismatch — onnxruntime-gpu expects cudnn64_9.dll (cuDNN 9.x)
fix
Install cuDNN 9.x or use CPU: pip install onnxruntime instead of onnxruntime-gpu
FaceAnalysis CUDAExecutionProvider silently falls back to CPUExecutionProvider
CUDA not available but CUDAExecutionProvider listed — onnxruntime falls back silently
fix
Check active providers: app = FaceAnalysis(); print(app.det_model.session.get_providers())
ModuleNotFoundError: No module named 'insightface'
insightface or a required dep (onnxruntime, opencv-python, numpy<2) not installed
fix
pip install insightface onnxruntime opencv-python "numpy<2"
RuntimeError: unexpected EOF, expected 65474 more bytes.
Model file download was interrupted or corrupted
fix
Delete ~/.insightface/models/ and let insightface re-download
[ONNXRuntimeError] : 6 : RUNTIME_EXCEPTION : The input tensor cannot be reshaped to the requested shape.
Input image dimensions incompatible with model expected shape
fix
Ensure image is RGB uint8 and resize to model input size before passing
Upgrade
Version history
1.0.1latest on PyPI · released May 23, 2026
Audit
Dependencies
onnxruntimerequiredRequired for CPU inference backend (from insightface>=0.2 onwards).
onnxruntime-gpuoptionalRequired for GPU inference backend (alternative to onnxruntime, from insightface>=0.2 onwards). Requires compatible CUDA and cuDNN installation.
opencv-pythonrequiredCommonly used for image processing and I/O with InsightFace.
numpyrequiredVersion constraint (<2) recommended for compatibility with ONNX ecosystem.
PillowoptionalFrequently used for image loading and manipulation in Python imaging tasks.
Agent activity
161 hits · last 30 days
node
148
Perplexity
1
Resources
insightface — pip install insightface · libregistry