InsightFacePythonInsightFace ServerOptional RGB liveness

Enable optional RGB liveness in Python and InsightFace Server

Add checks before recognition and receive per-face status and scores. Configure recognition gating or observation mode for detection, comparison, search, and RTSP workflows.

2026-09-08•5 min read

What you will build

Face analysis in Python, with optional RGB liveness before recognition and per-face results.

Disabled by default. Enrollment checks have a separate setting.

Before you start

The updated InsightFace 2 source checkout containing python-package/docs/liveness.md, with Python 3.10+ and its package dependencies installed. This guide targets that source version; an older installed package may not expose the addon API.
A local input.jpg containing a face with surrounding image area, plus access to install the base model and liveness addon. Apply the terms supplied with each model.
For Server, use the deployment from the Docker guide and its existing configuration. The containers already run as root with writable model and configuration directories. CLI activation can run before the first Server startup.

1. Run an explicit Python liveness check

From the updated repository root, install the Python package into your active virtual environment. Place input.jpg in your working directory before running the example. The CPU example selects detection and recognition; addons=['liveness'] enables the separate liveness model.

The first run can download missing models. The addon is stored at ~/.insightface/addons/liveness.onnx and its SHA-256 is checked before loading. Installing the file alone does not enable it: keep addons=['liveness'] explicit. Omitting addons leaves liveness off.

Install from the updated source checkout

cd python-package
python -m pip install .

CPU example with per-face liveness results

import cv2
from insightface.app import FaceAnalysis

image_bgr = cv2.imread("input.jpg")
if image_bgr is None:
    raise FileNotFoundError("input.jpg")

app = FaceAnalysis(
    name="buffalo_l",
    allowed_modules=["detection", "recognition"],
    addons=["liveness"],
    liveness_mode="normal",
    liveness_threshold=0.8,
    providers=["CPUExecutionProvider"],
)
app.prepare(ctx_id=-1, det_size=(640, 640))

for face in app.get(image_bgr):
    print(face.liveness)
    if face.liveness is not None:
        print(
            face.liveness.status,
            face.liveness.is_live,
            face.liveness.live_score,
        )

2. Read results and choose the recognition policy

In normal mode, recognition runs only when is_live is True; other faces remain in the returned list with detection results but no embedding. In observe mode, recognition continues for non-live or rejected input while retaining liveness results. Model, alignment, and inference failures still raise exceptions in both modes.

status='ok': is_live is True or False, and live_score is a number in [0, 1]. The default threshold is 0.8; a score equal to the threshold passes. Validate the threshold on representative inputs using your deployment's execution provider.
status='input_rejected': is_live and live_score are None. This means there is insufficient source-image area around the aligned face, not a spoof classification. Recenter the face, step back, or use a less tightly cropped image; reason explains the issue.
face.liveness is None when the addon was not selected; no detected faces returns []. Use status and is_live in program logic. The Python/API reason text is English and should not be parsed as a stable status code.

Optional: enable RGB liveness

Yes. Add --enable-liveness during model installation, or enable it through System → Liveness in the Web UI, then start or restart Server. Normal mode gates recognition; observe mode reports results while continuing recognition. Liveness is off by default and enrollment has a separate switch.

For a new deployment, append --enable-liveness to the model-install command in the Docker deployment guide. Installation verifies the required models and saves the activation settings before the first startup.

For an existing deployment, use the matching command below, then restart the server. Plain model installation and models addons install liveness only install models; they do not enable liveness.

Alternatively, open System → Liveness and choose Download and enable after restart. Web and CLI installation verify the model and add liveness to inference.addons and addons.auto_download while preserving other entries and settings. A download failure does not enable liveness; wait for configuration saving to succeed before restarting.

For a fresh deployment, start the service after installation. For an existing deployment, run the restart command below; use the CUDA command for CUDA 12. In System, confirm enabled=true and restart_required=false. installed describes the verified model file and configured_enabled the saved setting. Changed mounts require container recreation.

Liveness is off by default. The Web action leaves enrollment unchanged; liveness_on_registration=false remains the default. Set it separately to true to apply the configured normal/observe policy during enrollment. To disable liveness, save empty lists for both inference.addons and addons.auto_download, then restart.

CPU

docker compose -f server/deploy/compose.cpu.yml run --rm models install buffalo_l --accept-license --enable-liveness

CUDA 12

docker compose -f server/deploy/compose.cuda12.yml run --rm models install buffalo_l --accept-license --enable-liveness

Apply saved settings to the existing CPU deployment

docker compose -f server/deploy/compose.cpu.yml restart server

Apply saved settings to the existing CUDA 12 deployment

docker compose -f server/deploy/compose.cuda12.yml restart server

Need help with production deployment?

Contact InsightFace for model licensing, runtime optimization, and deployment support for your target hardware.

Submit Enterprise Inquiry