🌐 Company Site - Here
🤗 Hugging Face - Here
📚 Help Center - Here
🐳 Docker Hub - Here
Fast edition — face recognition + passive liveness with TAR 99.4% @ FAR 1e-4 (TAR 98.5% @ FAR 1e-6). For high-accuracy match / PAD at stricter FAR, use FaceRecognition-Docker-v2.
Public repo: FaceRecognition-Docker.
- Docker (recommended):
docker pull faceplugin/face-recognition-liveness-sdk:latestthendocker run— Option A - Or local: download CPU runtime into
lib/cpu/— Option B, then./run.sh— API on 8083 - Confirm it is running:
curl -s http://127.0.0.1:8083/api/health(no license needed yet) - Contact us with your machine code to obtain a license key, then activate with
POST /api/activate— Activate your license - Try it: Postman, curl, or local Gradio demo on 9003 (
python3 demo.py)
Docs: doc.faceplugin.com
Try online: Hugging Face Space
FacePlugin Face Recognition SDK combines on-premise face recognition and passive face liveness detection (PAD) in one product for Linux and Docker. It runs face detection (bounding box, landmarks, pose, attributes), ICAO-style face quality analysis, template extraction, 1:1 matching, feature similarity scoring, and passive presentation-attack detection.
The SDK uses one wrapper (libFaceRecognitionSDK.so), one license, and two packs (far.fpk + fal.fpk). Your license unlocks Recognition only, Liveness only, or both. Built for banking, eKYC, and on-premise compliance. All processing runs on your own server — no images or biometric data are ever sent to FacePlugin.
The SDK runs as a REST API server on Linux (x86_64), or through Docker on Linux, Windows, and macOS (Apple Silicon uses amd64 emulation). It runs on CPU only and requires LD_PRELOAD of the wrapper for liveness VFS hooks (./run.sh and the Dockerfile set this). This repository is self-contained, with no other FacePlugin repository required.
| Edition | Repository | Fit | Speed / accuracy |
|---|---|---|---|
| Fast (this repo) | FaceRecognition-Docker | Throughput-oriented recognition path | Extract 59 ms; liveness check 559 ms; TAR 99.4% @ FAR 1e-4 |
| High-accuracy (v2) | FaceRecognition-Docker-v2 | Strict eKYC / bank-grade match & PAD | Feature 1750 ms; liveness check 559 ms; TAR ≥ 99.9% @ FAR ≤ 0.1% |
Same REST API shape on both editions. Windows pairs: FaceRecognition-Windows (fast) and FaceRecognition-Windows-v2 (high-accuracy).
Performance snapshot (measured on Intel Core i9-13900T, Linux, CPU, warm runtime, single face, median / p50):
| Step | Latency | Accuracy / note |
|---|---|---|
| Recognition extract | 59 ms | detect + landmarks + template; TAR 99.4% @ FAR 1e-4; TAR 98.5% @ FAR 1e-6 |
| Liveness check | 559 ms | /api/liveness |
v2 reference (same host): feature 1750 ms; TAR ≥ 99.9% @ FAR ≤ 0.1%. Prefer v2 when match / PAD accuracy is the priority; prefer this repo when you want the fast edition.
| Feature | API |
|---|---|
| Face detection (bounding box, landmarks, pose, attributes) | POST /api/detect · sdk.detect |
| Face quality analysis (ICAO-style checks) | POST /api/quality · sdk.quality |
| Face template extraction for matching | POST /api/feature · sdk.feature |
| 1:1 face match (two images) | POST /api/match · sdk.match |
| Feature vector similarity scoring | POST /api/similarity · sdk.similarity |
| Face liveness (passive PAD) | POST /api/liveness · sdk.liveness |
| License capabilities | GET /api/licenseStatus · sdk.get_license_status |
| Health / machine code / activate | GET /api/health · GET /api/machinecode · POST /api/activate |
| Platform | Repository |
|---|---|
| Android (Recognition) | FaceRecognition-Android |
| iOS (Recognition) | FaceRecognition-iOS |
| React Native (Recognition) | FaceRecognition-React-Native |
| Flutter (Recognition) | FaceRecognition-Flutter |
| Ionic Capacitor (Recognition) | FaceRecognition-Ionic-Capacitor |
| Ionic Cordova (Recognition) | FaceRecognition-Ionic-Cordova |
| Windows (Recognition + Liveness, fast) | FaceRecognition-Windows |
| Windows (Recognition + Liveness, high-accuracy v2) | FaceRecognition-Windows-v2 |
| Linux / Docker (Recognition + Liveness, fast) | FaceRecognition-Docker (this repo) |
| Linux / Docker (Recognition + Liveness, high-accuracy v2) | FaceRecognition-Docker-v2 |
| Android (Liveness) | FaceLivenessDetection-Android |
| iOS (Liveness) | FaceLivenessDetection-iOS |
| Windows (Liveness) | FaceLivenessDetection-Windows |
| Linux / Docker (Liveness) | FaceLivenessDetection-Docker |
You do not need a license to start the API. The server prints your machine code on startup, which you'll need to activate your license. Product endpoints unlock after you activate.
| Item | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Disk | 4 GB | 8 GB |
| OS (Docker) | Linux + Docker Engine | Ubuntu 22.04 / 24.04 |
The runtime is already inside the image, so no Google Drive download is needed.
sudo docker pull faceplugin/face-recognition-liveness-sdk:latest
sudo docker run -d --name faceplugin-face-recognition-liveness-sdk \
--shm-size=2gb --privileged \
-p 8083:8083 \
-v /etc/machine-id:/etc/machine-id:ro \
faceplugin/face-recognition-liveness-sdk:latest
sudo docker logs -f faceplugin-face-recognition-liveness-sdk
# Look for the machine code line in the logsOn Docker Desktop (macOS/Windows) omit the /etc/machine-id volume.
To run multiple containers on one Linux host with a shared machine code / license, see the docs:
This option runs the server directly on your machine. It requires glibc 2.38 or newer (for example, Ubuntu 24.04). Check your version with ldd --version. No GPU is needed; this product runs on CPU only.
git clone https://github.com/Faceplugin-ltd/FaceRecognition-Docker.git
cd FaceRecognition-DockerThe lib/cpu/ folder is empty on GitHub because the native libraries and model files are too large to host there.
- Open the FaceRecognition-Linux-fast runtime folder on Google Drive.
- Download every file in the folder.
- Place the files directly in
lib/cpu/, not in a subfolder.
Your project should look like this:
FaceRecognition-Docker/
└── lib/
└── cpu/
├── libFaceRecognitionSDK.so
├── libfacerec.so
├── far.fpk
├── libfal-eng.so
├── fal.fpk
├── libonnxruntime.so
└── libonnxruntime_providers_shared.so
⚠️ If Google Drive gives you a zip, extract it and move the files up so you don't end up withlib/cpu/SomeFolder/libFaceRecognitionSDK.so.
pip3 install -r requirements.txt
./run.shThe API starts at http://127.0.0.1:8083, and the machine code is printed in the terminal. Continue with Activate your license.
Licenses work offline and are tied to the machine code of the environment where the server runs. Offline cryptography is built into the SDK, so no OpenSSL install is needed.
⚠️ Docker and local installs have different machine codes. Get the machine code from the same environment you'll use in production. If you'll run in Docker, send the code from the Docker container, not from the host.
-
Start the server using Docker Hub or
./run.sh(see Start the API). You don't need a license for the first start. -
Get your machine code. It's printed in the startup log, or you can fetch it with
GET /api/machinecode. -
Send the machine code to FacePlugin (contact us). We'll reply with a license key for that machine code.
-
Activate the license. Save the license key to
license.txtin the project root, replacing anything already in the file. Then send it to the running server:curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txtIf you run in Docker, this command is required, because detached containers don't re-read
license.txtafter they start. The same command also works with./run.sh.
After activation, GET /api/licenseStatus reports what the key unlocks. The Gradio demo shows the same summary as License: at the top of the page.
| Capability | Meaning |
|---|---|
| Recognition | Detect, quality, match, feature, similarity |
| Liveness | Passive face anti-spoofing (/api/liveness) |
Typical labels:
- Recognition + Liveness — full product (all tabs)
- Recognition only — Detect / Quality / Match; Liveness stays unavailable
- Liveness only — Liveness tab; Detect / Quality / Match stay unavailable
- Not licensed — machine code only until you activate
Check status anytime:
curl -s http://127.0.0.1:8083/api/licenseStatuscurl -s http://127.0.0.1:8083/api/healthImport postman/FaceRecognition-API.postman_collection.json.
Default base URL: http://127.0.0.1:8083
The Docker image includes only the API server, not the demo UI. To view results in your browser, run the Gradio demo on your own machine. Make sure the API is already running on port 8083 first.
pip3 install -r requirements-demo.txt
DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.pyOpen http://127.0.0.1:9003 in your browser. Sample images, if included, are in assets/examples/samples/. The page header shows your current license status, taken from /api/licenseStatus. All tabs stay visible; a capability your license doesn't cover shows a note instead of results.
- Detect — bounding box, landmarks, pose, and attributes
- Quality — ICAO-style face quality checks
- Match — 1:1 match scores; pick one image from the Odd group and one from the Even group, then Match
- Liveness — passive Real / Spoof score (needs a Liveness-capable license)
Each tab shows a Result table and Raw JSON for integration. The examples under assets/examples/samples/ include odd/even faces and real/fake liveness samples.
Two paths. You do not need the Gradio demo (demo.py) in production; it is a host-only test UI.
HTTP (any language) — start the API (see Start the API) and keep it running, then POST base64 images as JSON to /api/detect, /api/quality, /api/match, /api/feature, /api/similarity, or /api/liveness. See the Postman collection for request examples, and doc.faceplugin.com for the full protocol.
Python in-process — on the same Linux host as lib/cpu/ (or inside the container), copy sdk.py + lib/cpu/ into your project (or import sdk from this repo) and call the SDK directly, with no HTTP hop. For native runs, set LD_LIBRARY_PATH and LD_PRELOAD the same way ./run.sh does. See About SDK.
Use the Python bindings in sdk.py. Return code 0 means success.
First, obtain the machine code for activation and request a license based on the machine code.
import sdk
machine_code = sdk.get_machine_code()
print("machineCode:", machine_code) # machine codeNext, activate the SDK with the path to your license file (license.txt containing your license key).
ret = sdk.activate("license.txt")If activation is successful, the return value will be 0. Otherwise, an error value will be returned.
After activation, call the initialization function of the SDK.
ret = sdk.init_sdk()If initialization is successful, the return value will be 0. Otherwise, an error value will be returned.
result = sdk.detect(base64_image, crop_image=False)result = sdk.quality(base64_image, crop_image=False)result = sdk.feature(base64_image)result = sdk.match(base64_image1, base64_image2, crop_image=False)result = sdk.similarity(feature1_b64, feature2_b64)result = sdk.liveness(base64_image)status = sdk.get_license_status()
# recognition / liveness flags, label, level 0|1|2HTTP endpoints: /api/health, /api/machinecode, /api/licenseStatus, /api/backend, /api/activate, /api/detect, /api/quality, /api/match, /api/feature, /api/similarity, /api/liveness.
Request a license, machine-code activation (machine code → license key), or integration help:






