---
id: insightface
version: "1.0.1"
license: unclear
license_treatment: unclear
maintenance: active
---

# insightface — InsightFace Python Library

License: unclear · Maintenance: active · Downloads: 1.1M/mo

## What it is and what it does

InsightFace is a deep learning library for face analysis tasks—detection, recognition, alignment, and attribute extraction—built on onnxruntime inference. It ships with a cross-platform desktop GUI (InsightFace Evaluation Studio) for local 1:1 face comparison, 1:N gallery search, album clustering with DBSCAN, batch processing, and face swap trials, all with data stored locally by default.

The library provides FaceAnalysis as its main entry point, supporting multiple detection and recognition model packs (buffalo_l, antelopev2, etc.) with configurable execution providers for CPU or GPU. Models are downloaded on demand or manually; the GUI includes a model manager for explicit downloads and optional GFPGAN post-processing for face restoration. The optional face3d extension can be built for legacy mask rendering.

Use it for:

- Build a face recognition system to identify or verify individuals in photos or video streams using pretrained models.
- Create a local face search application to find similar faces across a gallery of images without uploading data.
- Cluster and organize photo albums by detected faces using the GUI's DBSCAN-based grouping with cosine similarity threshold of 0.48.
- Generate face embeddings for downstream machine learning tasks like clustering, classification, or similarity matching.
- Run batch face detection and attribute extraction (gender, age) across folders of images for analysis or reporting.
- Evaluate face recognition performance on enterprise datasets with the GUI's evaluation workspace and PDF report export.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

InsightFace is a Python library for face detection, recognition, alignment, and attribute analysis using deep learning models, with a desktop GUI for local face comparison, search, clustering, and face swap operations.

Yes, with conditions. Install if you need local face detection, recognition, or analysis and accept the non-commercial model licensing restriction. The library is actively maintained, has low install friction, and offers both programmatic and GUI interfaces. Verify that your use case complies with the pretrained model license before deploying commercially.

## Install

pip install insightface
uv add insightface
poetry add insightface

## Installing insightface

Before you install: Low install friction with a pure Python wheel and eight common dependencies (numpy, onnxruntime, opencv-python, scipy, scikit-image, requests, tqdm, onnx). The library is actively maintained with recent releases and high repository engagement.

License in practice: Code is MIT-licensed with no commercial restriction, but pretrained models are available for non-commercial research purposes only—commercial use requires separate model licensing.

Quickstart:

pip install insightface

from insightface.app import FaceAnalysis
from insightface.data import get_image as ins_get_image

app = FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
app.prepare(ctx_id=0)
img = ins_get_image('t1')
faces = app.get(img)

onnxruntime must be installed separately; use onnxruntime-gpu for GPU inference or onnxruntime for CPU-only. Models are not auto-downloaded; manual download and extraction to ~/.insightface/models/ may be required depending on the model pack.

Verify before relying:

- Minimum Python version requirement (requires_python not specified in metadata)
- Whether pretrained model licensing restrictions apply to your intended use case
- GPU support details and CUDA/cuDNN version compatibility
- Performance benchmarks for different detection sizes and model packs

## Package facts

- License: not declared (unclear)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

face detection and recognition, face alignment and attributes, face comparison and search, face clustering and grouping, face swap tool, facial analysis library, local face recognition gui, face-recognition, computer-vision, desktop-gui

[View on SkillFed](https://skillfed.io/packages/insightface) · [View on PyPI](https://pypi.org/project/insightface/)