Linux

Faceplugin Face Recognition API for Linux Docker. On-premise detect, match, and similarity on port 8083. Offline after license activation.

Fully on-premise Face Recognition API for Linux / Docker. Image: faceplugin/face-recognition. Default port 8083.

This product is recognition only. For recognition and liveness in the same container, use Face Recognition + Liveness Linux SDK (faceplugin/face-recognition-liveness-sdk). Or run Face Liveness Detection Linux SDK on port 8084 as a second container.

All processing stays on your server. No biometric data is sent to Faceplugin cloud.

Code

GitHub - Faceplugin-ltd/FaceRecognition-Docker: Face Recognition, Face Detection, Face Landmarks, Face Compare, Face Matching, Face Pose, Face Expression, Face Attributes, Face Templates Extraction, Face LandmarksGitHub

Setup

Sizing: Hosting requirements.

1

Pull from Docker Hub (no Google Drive download)

sudo docker pull faceplugin/face-recognition:latest
sudo docker run -d --name faceplugin-face-recognition \
  --shm-size=2gb --privileged \
  -p 8083:8083 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-recognition:latest

On Docker Desktop (macOS/Windows) omit the /etc/machine-id volume.

2

Confirm health (no license yet)

curl -s http://127.0.0.1:8083/api/health

3

Copy the machine code

curl -s http://127.0.0.1:8083/api/machinecode

Send machine code to Faceplugin. Docker and local host codes are different.

4

Activate

Put your key in license.txt, then:

curl -s -X POST http://127.0.0.1:8083/api/activate \
  -H 'Content-Type: text/plain' \
  --data-binary @license.txt

Run multiple containers with one license

You only need this section if you want to run multiple Face Recognition containers on the same Linux host.

On Linux, mount /etc/machine-id into each container so they use the same machine code. Each container must have a different container name and host port.

For example:

sudo docker run -d --name faceplugin-face-recognition-2 \
  --shm-size=2gb --privileged \
  -p 8084:8083 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-recognition:latest

Activate each container with the same license key (POST /api/activate on each host port).

On Docker Desktop (macOS/Windows), omit the /etc/machine-id volume. Each container may require its own license.

Other ways to run

Option B — Docker Compose (local build)

git clone https://github.com/Faceplugin-ltd/FaceRecognition-Docker.git
cd FaceRecognition-Docker

Put the Google Drive runtime files directly in lib/cpu/, then:

# macOS/Windows Docker Desktop: remove the /etc/machine-id volume from docker-compose.yml first
sudo docker compose up --build -d
sudo docker compose logs -f

Option C — Native Linux (no Docker)

Same lib/cpu/ layout. Needs glibc 2.38+ (for example Ubuntu 24.04).

pip3 install -r requirements.txt
./run.sh

Control routes (/api/health, /api/machinecode, /api/activate, /api/licenseStatus) return a JSON envelope. Process POSTs (/api/detect, /api/quality, …) return engine JSON as the HTTP body.

License

Licenses are offline. Request a License & Support.

Try it

curl -s http://127.0.0.1:8083/api/health
IMG=$(base64 -w0 face.jpg)   # macOS: base64 -i face.jpg

curl -s -X POST http://127.0.0.1:8083/api/detect \
  -H 'Content-Type: application/json' \
  -d "{\"image\":\"$IMG\"}"

curl -s -X POST http://127.0.0.1:8083/api/match \
  -H 'Content-Type: application/json' \
  -d "{\"image1\":\"$IMG\",\"image2\":\"$IMG\"}"

Postman: import postman/FaceRecognition-API.postman_collection.json from the repo. Base URL http://127.0.0.1:8083. Paths have no /v1.

Gradio (host only): the Docker image is API-only. On the host:

pip3 install -r requirements-demo.txt
DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.py

Open http://127.0.0.1:9003. Tabs: Detect, Quality, Match.

Integrate into your own app

Path	When to use
HTTP (app.py)	Any language. Keep this API running and POST base64 JPEGs.
sdk.py	Python on the same Linux host as lib/cpu/ (or inside the container).

You do not need Gradio in production.

APIs

Endpoint	Purpose
GET /api/health	Process is listening (no license)
GET /api/machinecode	Machine code
GET /api/licenseStatus	License status
GET /api/backend	"cpu"
POST /api/activate	Activate and init_sdk()
POST /api/detect	Detect faces
POST /api/quality	Quality checks
POST /api/feature	Extract template
POST /api/match	Compare two photos
POST /api/similarity	Compare two templates

Full reference: Face Recognition HTTP API. Shared control routes: Shared endpoints.

Some routes wrap the result in a small JSON object (an envelope). Process POSTs return engine JSON as the body. There is no POST /api/identify (no server-side 1:N gallery).

Python:

import sdk

print(sdk.get_machine_code())
sdk.activate("license.txt")
sdk.init_sdk()
print(sdk.get_license_status())
print(sdk.detect(base64_image))
print(sdk.match(image1, image2))

Call order: get_machine_code → activate → init_sdk → detect / quality / feature / match / similarity.

Request a License & Support · Contact us

FAQ

Is this a Face Recognition API? Yes. Docker image faceplugin/face-recognition, port 8083: POST /api/detect, /api/match, /api/similarity.

Machine code? GET /api/machinecode returns machine code. Docker and host codes differ.

Server-side 1:N? No. There is no POST /api/identify gallery.

Related documentation

• Face Recognition HTTP API · Hosting requirements

• Faceplugin Face Recognition Server SDK · Windows · Glossary

• Face Liveness Detection Linux SDK

• ID Document Recognition Linux SDK

• Request a License · Status codes

• Architecture · SDK comparison