Immich ML GPU Cache Paths and Model Names

Known working for Immich v2.7.5.

Model Sources

All models hosted on HuggingFace under immich-app/ org.

Model Name	HuggingFace Repo	Files	Size
`ViT-B-32__openai`	`immich-app/ViT-B-32__openai`	visual/model.onnx (335 MB), textual/model.onnx (254 MB)	~590 MB total
`buffalo_l`	`immich-app/buffalo_l`	detection/model.onnx (16 MB), recognition/model.onnx (166 MB)	~182 MB total

Cache Directory Structure

Cache root: /cache (from MACHINE_LEARNING_CACHE_FOLDER env var).

CLIP (smart search)

Field	Value
Model task	`SEARCH` → `"clip"`
Model type	`VISUAL` → `"visual"`, `TEXTUAL` → `"textual"`
Cache dir	`/cache/clip/ViT-B-32__openai`
Model dir (visual)	`/cache/clip/ViT-B-32__openai/visual`
Model path (visual)	`/cache/clip/ViT-B-32__openai/visual/model.onnx`
Model dir (textual)	`/cache/clip/ViT-B-32__openai/textual`
Model path (textual)	`/cache/clip/ViT-B-32__openai/textual/model.onnx`

Face detection & recognition

Field	Value
Model task	`FACIAL_RECOGNITION` → `"facial-recognition"`
Cache dir	`/cache/facial-recognition/buffalo_l`
Model dir (detection)	`/cache/facial-recognition/buffalo_l/detection`
Model path (detection)	`/cache/facial-recognition/buffalo_l/detection/model.onnx`
Model dir (recognition)	`/cache/facial-recognition/buffalo_l/recognition`
Model path (recognition)	`/cache/facial-recognition/buffalo_l/recognition/model.onnx`

Code Derivation

Cache paths follow this pattern:

from immich_ml.config import settings
# settings.cache_folder = "/cache"
# model_task.value = one of: "clip", "facial-recognition", "ocr"
# model_name = e.g. "ViT-B-32__openai" or "buffalo_l"
# model_type.value = one of: "visual", "textual", "detection", "recognition"

cache_dir = settings.cache_folder / model_task.value / model_name
model_dir = cache_dir / model_type.value
model_path = model_dir / "model.onnx"

Pre-download command

from huggingface_hub import snapshot_download
import os

# For CLIP
os.makedirs("/cache/clip/ViT-B-32__openai", exist_ok=True)
snapshot_download(
    "immich-app/ViT-B-32__openai",
    cache_dir="/cache/clip/ViT-B-32__openai",
    local_dir="/cache/clip/ViT-B-32__openai",
    ignore_patterns=["*.armnn", "*.rknn"],
)

# For face detection/recognition
os.makedirs("/cache/facial-recognition/buffalo_l", exist_ok=True)
snapshot_download(
    "immich-app/buffalo_l",
    cache_dir="/cache/facial-recognition/buffalo_l",
    local_dir="/cache/facial-recognition/buffalo_l",
    ignore_patterns=["*.armnn", "*.rknn"],
)

docker-compose GPU config

Required addition to immich-machine-learning service:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

Environment variables

Variable	Value	Effect
`DEVICE`	`cuda`	Use CUDA (set by -cuda image)
`MACHINE_LEARNING_MODEL_ARENA`	`false`	Load all models at once. Set `true` to load one at a time (saves VRAM but slower switching)
`MACHINE_LEARNING_DEVICE_ID`	`0`	GPU device index
`MACHINE_LEARNING_CACHE_FOLDER`	`/cache`	Where models are stored

3.3 KiB Raw Permalink Blame History