← Back to Guides
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.

•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: an updated, running Linux deployment with its base model installed. The Server user (UID/GID 10001 in Compose) needs write access to the mounted addons directory and the whole configuration directory for Web installation.

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.

3. Install, restart, and verify in Server

Yes. Install and enable the optional RGB liveness addon through the Server Web UI. Normal mode gates recognition on the liveness result; observe mode reports results while continuing recognition. Liveness is off by default, and enrollment has a separate switch. See the liveness guide for setup and result interpretation.

Open System → Liveness and choose Download and enable after restart. The action downloads the published addon (or reuses a verified cache), verifies SHA-256, and saves ['liveness'] in inference.addons and addons.auto_download. Wait for successful installation and configuration before restarting.

Run the restart command from the repository root; use compose.cuda12.yml for CUDA. In System, confirm enabled is true and restart_required is false. installed describes the verified file, while configured_enabled describes the saved next-start setting: neither alone confirms running inference. 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.

Apply saved settings to the existing CPU deployment
docker compose -f server/deploy/compose.cpu.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