Skip to content

Model Cache & Offline Use

UniFace automatically downloads and caches models. This page explains how model management works.

Automatic Download

Models are downloaded on first use:

from uniface.detection import RetinaFace

# First run: downloads model to cache
detector = RetinaFace()  # ~3.5 MB download

# Subsequent runs: loads from cache
detector = RetinaFace()  # Instant

Cache Location

Default cache directory:

~/.uniface/models/

Example structure:

~/.uniface/models/
├── retinaface_mnet_v2.onnx
├── arcface_mnet.onnx
├── 2d_106.onnx
├── gaze_resnet34.onnx
├── parsing_resnet18.onnx
└── ...

Custom Cache Directory

Use the programmatic API to change the cache location at runtime:

from uniface.model_store import get_cache_dir, set_cache_dir

# Set a custom cache directory
set_cache_dir('/data/models')

# Verify the current path
print(get_cache_dir())  # /data/models

# All subsequent model loads use the new directory
from uniface.detection import RetinaFace
detector = RetinaFace()  # Downloads to /data/models/

Or set the UNIFACE_CACHE_DIR environment variable (see Environment Variables below).

Pre-Download Models

Download models before deployment using the concurrent downloader:

from uniface.model_store import download_models
from uniface.constants import (
    RetinaFaceWeights,
    ArcFaceWeights,
    AgeGenderWeights,
)

# Download multiple models concurrently (up to 4 threads by default)
paths = download_models([
    RetinaFaceWeights.MNET_V2,
    ArcFaceWeights.MNET,
    AgeGenderWeights.DEFAULT,
])

for model, path in paths.items():
    print(f"{model.value} -> {path}")

Or download one at a time:

from uniface.model_store import verify_model_weights
from uniface.constants import RetinaFaceWeights

path = verify_model_weights(RetinaFaceWeights.MNET_V2)
print(f"Downloaded: {path}")

Or use the CLI tool:

python tools/download_model.py

Offline Use

For air-gapped or offline environments:

1. Pre-download models

On a connected machine:

from uniface.model_store import verify_model_weights
from uniface.constants import RetinaFaceWeights

path = verify_model_weights(RetinaFaceWeights.MNET_V2)
print(f"Copy from: {path}")

2. Copy to target machine

# Copy the entire cache directory
scp -r ~/.uniface/models/ user@offline-machine:~/.uniface/models/

3. Point to the cache (if non-default location)

from uniface.model_store import set_cache_dir

# Only needed if the models are not at ~/.uniface/models/
set_cache_dir('/path/to/copied/models')

4. Use normally

# Models load from local cache
from uniface.detection import RetinaFace
detector = RetinaFace()  # No network required

Model Verification

Models are verified with SHA-256 checksums:

from uniface.constants import MODEL_SHA256, RetinaFaceWeights

# Check expected checksum
expected = MODEL_SHA256[RetinaFaceWeights.MNET_V2]
print(f"Expected SHA256: {expected}")

If a model fails verification, it's re-downloaded automatically.

Available Models

Detection Models

Model Size Download
RetinaFace MNET_025 1.7 MB ✅
RetinaFace MNET_V2 3.5 MB ✅
RetinaFace RESNET34 56 MB ✅
SCRFD 500M 2.5 MB ✅
SCRFD 10G 17 MB ✅
YOLOv5n-Face 11 MB ✅
YOLOv5s-Face 28 MB ✅
YOLOv5m-Face 82 MB ✅
YOLOv8-Lite-S 7.4 MB ✅
YOLOv8n-Face 12 MB ✅

Recognition Models

Model Size Download
ArcFace MNET 8 MB ✅
ArcFace RESNET 166 MB ✅
MobileFace MNET_V2 4 MB ✅
SphereFace SPHERE20 50 MB ✅

Other Models

Model Size Download
Landmark106 14 MB ✅
AgeGender 8 MB ✅
FairFace 44 MB ✅
Gaze ResNet34 82 MB ✅
BiSeNet ResNet18 51 MB ✅
MiniFASNet V2 1.2 MB ✅

Clear Cache

Find and remove cached models:

from uniface.model_store import get_cache_dir
print(get_cache_dir())  # shows the active cache path

# Remove all cached models
rm -rf ~/.uniface/models/

# Remove specific model
rm ~/.uniface/models/retinaface_mv2.onnx

Models will be re-downloaded on next use.

Environment Variables

There are three equivalent ways to configure the cache directory:

1. Programmatic API (recommended)

from uniface.model_store import get_cache_dir, set_cache_dir

set_cache_dir('/path/to/custom/cache')
print(get_cache_dir())  # /path/to/custom/cache

2. Direct environment variable (Python)

import os
os.environ['UNIFACE_CACHE_DIR'] = '/path/to/custom/cache'

from uniface.detection import RetinaFace
detector = RetinaFace()  # Uses custom cache

3. Shell environment variable

export UNIFACE_CACHE_DIR=/path/to/custom/cache

All three methods set the same UNIFACE_CACHE_DIR environment variable under the hood. get_cache_dir() always returns the resolved path.

Next Steps