Skip to content

Installation

This guide covers all installation options for UniFace.

Requirements

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

Why Two Extras?

onnxruntime (CPU) and onnxruntime-gpu (CUDA) both own the same Python namespace. Installing both at the same time causes file conflicts and silent provider mismatches. UniFace exposes them as separate, mutually exclusive extras so you install exactly one.

Quick Install

pip install uniface[cpu]

pip install uniface[gpu]

Platform-Specific Installation

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

The [cpu] extra pulls in the standard onnxruntime package, which has native ARM64 support built in since version 1.13. No additional setup is needed for CoreML acceleration.

pip install uniface[cpu]

Native Performance

onnxruntime 1.13+ includes ARM64 optimizations out of the box. UniFace automatically detects and enables CoreMLExecutionProvider on Apple Silicon.

Verify ARM64 installation:

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

Linux/Windows with NVIDIA GPU

pip install uniface[gpu]

This installs onnxruntime-gpu, which includes both CUDAExecutionProvider and CPUExecutionProvider — no separate CPU package is needed.

Requirements:

  • NVIDIA driver compatible with your CUDA version
  • CUDA 11.x or 12.x toolkit
  • cuDNN 8.x

CUDA Compatibility

See the ONNX Runtime GPU compatibility matrix for matching CUDA and cuDNN versions.

Verify GPU installation:

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

CPU-Only (All Platforms)

pip install uniface[cpu]

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 ".[cpu]"   # CPU / Apple Silicon
pip install -e ".[gpu]"   # NVIDIA GPU

With development dependencies:

pip install -e ".[cpu,dev]"

FAISS Vector Store

For fast multi-identity face search using a FAISS vector store:

pip install faiss-cpu   # CPU
pip install faiss-gpu   # NVIDIA GPU (CUDA)

See the Stores module for usage.

Dependencies

UniFace has minimal core dependencies:

Package Purpose
numpy Array operations
opencv-python Image processing
scikit-image Geometric transforms
scipy Signal processing
requests Model download
tqdm Progress bars

Runtime extras (install exactly one):

Extra Package Use case
uniface[cpu] onnxruntime CPU inference, Apple Silicon
uniface[gpu] onnxruntime-gpu NVIDIA CUDA inference

Other optional packages:

Package Install Purpose
faiss-cpu / faiss-gpu pip install faiss-cpu FAISS vector store
torch pip install torch Emotion model (TorchScript)
torchvision pip install torchvision Faster NMS for YOLO detectors

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.detection import RetinaFace
detector = RetinaFace()
print("Installation successful!")

Upgrading

When upgrading UniFace, stay consistent with your runtime extra:

pip install --upgrade uniface[cpu]   # or uniface[gpu]

If you are switching from CPU to GPU (or vice versa):

pip uninstall onnxruntime onnxruntime-gpu -y
pip install uniface[gpu]   # install the one you want

Pre-release Versions

UniFace ships release candidates and betas to PyPI ahead of stable releases (versions like 0.7.0rc1, 0.7.0b1, 0.7.0a1). These let you try upcoming features before they're finalized.

pip install uniface always installs the latest stable release. To opt in to pre-releases:

# Latest pre-release (if newer than latest stable)
pip install uniface[cpu] --pre

# A specific pre-release
pip install uniface[cpu]==0.7.0rc1

Pre-releases are not recommended for production — APIs may still change before the stable release.

Troubleshooting

onnxruntime Not Found

If you see:

ImportError: onnxruntime is not installed. Install it with one of:
  pip install uniface[cpu]   # CPU / Apple Silicon
  pip install uniface[gpu]   # NVIDIA GPU (CUDA)

You installed uniface without an extra. Run the appropriate command above.

Both onnxruntime and onnxruntime-gpu Installed

If you previously ran pip install uniface[gpu] on top of a pip install uniface[cpu] (or vice versa), you may have both packages installed simultaneously, which causes conflicts. Fix it with:

pip uninstall onnxruntime onnxruntime-gpu -y
pip install uniface[gpu]   # or uniface[cpu]

Import Errors

Ensure you're using Python 3.10+:

python --version
# Should show: Python 3.10.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}")

CUDA Not Detected

  1. Verify CUDA installation: 

    nvidia-smi

  2. Check CUDA version compatibility with ONNX Runtime.

  3. Reinstall the GPU extra cleanly: 

    pip uninstall onnxruntime onnxruntime-gpu -y
pip install uniface[gpu]

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