{"id":4579,"library":"insightface","title":"InsightFace Python Library","description":"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.","status":"active","version":"0.7.3","language":"en","source_language":"en","source_url":"https://github.com/deepinsight/insightface","tags":["face recognition","face detection","deep learning","computer vision","onnx","machine learning"],"install":[{"cmd":"pip install insightface","lang":"bash","label":"Basic Installation"},{"cmd":"pip install insightface onnxruntime opencv-python \"numpy<2\"","lang":"bash","label":"Recommended CPU Installation"},{"cmd":"pip install insightface onnxruntime-gpu opencv-python \"numpy<2\"","lang":"bash","label":"Recommended GPU Installation (requires CUDA/cuDNN)"}],"dependencies":[{"reason":"Required for CPU inference backend (from insightface>=0.2 onwards).","package":"onnxruntime","optional":false},{"reason":"Required for GPU inference backend (alternative to onnxruntime, from insightface>=0.2 onwards). Requires compatible CUDA and cuDNN installation.","package":"onnxruntime-gpu","optional":true},{"reason":"Commonly used for image processing and I/O with InsightFace.","package":"opencv-python","optional":false},{"reason":"Version constraint (<2) recommended for compatibility with ONNX ecosystem.","package":"numpy","optional":false},{"reason":"Frequently used for image loading and manipulation in Python imaging tasks.","package":"Pillow","optional":true}],"imports":[{"symbol":"FaceAnalysis","correct":"from insightface.app import FaceAnalysis"},{"symbol":"get_image","correct":"from insightface.data import get_image"}],"quickstart":{"code":"import cv2\nimport numpy as np\nimport insightface\nfrom insightface.app import FaceAnalysis\nfrom insightface.data import get_image as ins_get_image\n\n# Initialize FaceAnalysis app with desired providers (e.g., CUDA or CPU)\n# Ensure onnxruntime-gpu is installed for CUDAExecutionProvider\napp = FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])\napp.prepare(ctx_id=0, det_size=(640, 640))\n\n# Load a sample image\nimg = ins_get_image('t1') # 't1' is a sample image bundled with the library\n\n# Perform face detection and analysis\nfaces = app.get(img)\n\n# Draw results on the image\nrimg = app.draw_on(img, faces)\n\n# Display or save the output image\n# cv2.imshow(\"InsightFace Demo\", rimg)\n# cv2.waitKey(0)\n# cv2.destroyAllWindows()\ncv2.imwrite(\"./t1_output.jpg\", rimg)\nprint(f\"Detected {len(faces)} face(s). Output saved to t1_output.jpg\")\n\nif faces:\n    face = faces[0]\n    print(f\"Face 0: Bounding Box: {face.bbox}, Landmark: {face.landmark}\")\n    if face.embedding is not None:\n        print(f\"Face 0: Embedding shape: {face.embedding.shape}\")\n    if face.gender is not None:\n        print(f\"Face 0: Gender: {face.gender}, Age: {face.age}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment has `onnxruntime` or `onnxruntime-gpu` installed. Convert any custom MXNet models to ONNX format.","message":"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.","severity":"breaking","affected_versions":"insightface>=0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"insightface>=0.2 (when using GPU)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly during `pip install`."},{"fix":"Explicitly install `NumPy` with a version constraint: `pip install \"numpy<2\"`.","message":"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.","severity":"gotcha","affected_versions":"Recent insightface versions (0.7.x) with onnx/onnxruntime"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions that auto-download models from Google Drive."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}