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
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.fixEnsure 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.fixCarefully 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.fixReview 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.fixOn 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.fixExplicitly 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.fixManually 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)
fixInstall 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
fixCheck 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
fixpip install insightface onnxruntime opencv-python "numpy<2"
RuntimeError: unexpected EOF, expected 65474 more bytes.
Model file download was interrupted or corrupted
fixDelete ~/.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
fixEnsure 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.