Skip to content

Installation

This guide covers all installation options for UniFace.

Requirements

  • Python: 3.11 or higher
  • Operating Systems: macOS, Linux, Windows

Quick Install

The simplest way to install UniFace:

pip install uniface

This installs the CPU version with all core dependencies.

Platform-Specific Installation

macOS (Apple Silicon - M1/M2/M3/M4)

For Apple Silicon Macs, the standard installation automatically includes ARM64 optimizations:

pip install uniface

Native Performance

The base onnxruntime package has native Apple Silicon support with ARM64 optimizations built-in since version 1.13+. No additional configuration needed.

Verify ARM64 installation:

python -c "import platform; print(platform.machine())"
# Should show: arm64

Linux/Windows with NVIDIA GPU

For CUDA acceleration on NVIDIA GPUs:

pip install uniface[gpu]

Requirements:

  • CUDA 11.x or 12.x
  • cuDNN 8.x

CUDA Compatibility

See ONNX Runtime GPU requirements for detailed compatibility matrix.

Verify GPU installation:

import onnxruntime as ort
print("Available providers:", ort.get_available_providers())
# Should include: 'CUDAExecutionProvider'

CPU-Only (All Platforms)

pip install uniface

Works on all platforms with automatic CPU fallback.

Install from Source

For development or the latest features:

git clone https://github.com/yakhyo/uniface.git
cd uniface
pip install -e .

With development dependencies:

pip install -e ".[dev]"

Dependencies

UniFace has minimal dependencies:

Package Purpose
numpy Array operations
opencv-python Image processing
onnxruntime Model inference
requests Model download
tqdm Progress bars

Verify Installation

Test your installation:

import uniface
print(f"UniFace version: {uniface.__version__}")

# Check available ONNX providers
import onnxruntime as ort
print(f"Available providers: {ort.get_available_providers()}")

# Quick test
from uniface import RetinaFace
detector = RetinaFace()
print("Installation successful!")

Troubleshooting

Import Errors

If you encounter import errors, ensure you're using Python 3.11+:

python --version
# Should show: Python 3.11.x or higher

Model Download Issues

Models are automatically downloaded on first use. If downloads fail:

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

# Manually download a model
model_path = verify_model_weights(RetinaFaceWeights.MNET_V2)
print(f"Model downloaded to: {model_path}")

Performance Issues on Mac

Verify you're using the ARM64 build (not x86_64 via Rosetta):

python -c "import platform; print(platform.machine())"
# Should show: arm64 (not x86_64)

Next Steps