From eb3c0a0f00783828fd97ab25bffb1b6ace8c1126 Mon Sep 17 00:00:00 2001
From: Brian Pooe <bria.method@gmail.com>
Date: Sat, 27 Jun 2026 12:31:30 +0200
Subject: [PATCH] feat(immich): switch to NVENC for transcoding and CUDA for ML
 inference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- immich-server: add runtime: nvidia + NVIDIA_DRIVER_CAPABILITIES=video,
  compute,utility to enable NVENC hardware H.264 transcoding
- immich-machine-learning: change image tag to :release-cuda so
  CUDAExecutionProvider is selected over CPUExecutionProvider for CLIP,
  face detection, and OCR
- Update GPU Verification section in README with verification commands
  and note on resetting QSV → NVENC in the admin UI
---
 docker-compose-files/immich/README.md     | 16 +++++++++++++---
 docker-compose-files/immich/template.yaml |  5 ++++-
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/docker-compose-files/immich/README.md b/docker-compose-files/immich/README.md
index 88a8a5a..f6f2b6e 100644
--- a/docker-compose-files/immich/README.md
+++ b/docker-compose-files/immich/README.md
@@ -112,10 +112,20 @@ Immich is deployed in a **Privileged LXC** to ensure:
 
 ## GPU Verification
 
-Once the stack is running, you can verify GPU usage by the Machine Learning container:
+Both `immich-server` and `immich-machine-learning` run with `runtime: nvidia`:
+
+- **immich-server** — uses NVENC for hardware-accelerated H.264 video transcoding (`NVIDIA_DRIVER_CAPABILITIES=video,compute,utility`)
+- **immich-machine-learning** — uses the `:release-cuda` image with `CUDAExecutionProvider` for CLIP embeddings, face detection, and OCR
+
+Verify GPU access after startup:
 
 ```bash
-docker exec -it immich_machine_learning nvidia-smi
+# Confirm NVIDIA device visible in server (needed for NVENC)
+docker exec immich_server ls /dev/nvidia0
+
+# Confirm CUDA ONNX provider active in ML container
+docker exec immich_machine_learning python3 -c 'import onnxruntime; print(onnxruntime.get_available_providers())'
+# Expected: ['TensorrtExecutionProvider', 'CUDAExecutionProvider', 'CPUExecutionProvider']
 ```
 
-You should see the RTX A400 listed. Immich will use this for facial recognition and object detection.
+After verifying, go to **Administration → Video Transcoding** in the Immich UI and confirm Hardware Acceleration is set to **NVENC**. If it shows QSV (from a prior config), change it to NVENC and re-run the Video Conversion job.
diff --git a/docker-compose-files/immich/template.yaml b/docker-compose-files/immich/template.yaml
index cc263e8..b87782c 100644
--- a/docker-compose-files/immich/template.yaml
+++ b/docker-compose-files/immich/template.yaml
@@ -5,6 +5,7 @@ services:
   immich-server:
     container_name: immich_server
     image: ghcr.io/immich-app/immich-server:{{IMMICH_VERSION:-release}}
+    runtime: nvidia
     volumes:
       - {{IMMICH_UPLOAD_LOCATION}}:/data
       - /etc/localtime:/etc/localtime:ro
@@ -24,6 +25,8 @@ services:
       - OAUTH_BUTTON_TEXT={{OIDC_NAME:-}}
       - OAUTH_AUTO_LAUNCH={{OIDC_AUTO_REDIRECT:-false}}
       - OAUTH_MOBILE_OVERRIDE_ENABLED={{OIDC_MOBILE_OVERRIDE_ENABLED:-false}}
+      - NVIDIA_VISIBLE_DEVICES=all
+      - NVIDIA_DRIVER_CAPABILITIES=video,compute,utility
       - DISABLE_PASSWORD_LOGIN={{OIDC_DISABLE_LOCAL_AUTH:-false}}
       # Email (optional - leave blank to disable)
       - SMTP_HOST={{EMAIL_HOST:-}}
@@ -51,7 +54,7 @@ services:
 
   immich-machine-learning:
     container_name: immich_machine_learning
-    image: ghcr.io/immich-app/immich-machine-learning:{{IMMICH_VERSION:-release}}
+    image: ghcr.io/immich-app/immich-machine-learning:{{IMMICH_VERSION:-release}}-cuda
     runtime: nvidia
     volumes:
       - {{IMMICH_DATA_DIR}}/model-cache:/cache