Immich hardware acceleration, both halves
Immich does two kinds of heavy lifting: transcoding videos so your library plays smoothly anywhere, and running machine learning — face recognition and smart search — over every photo you own. On CPU both are slow enough to feel broken on a big library. Your hardware almost certainly has a GPU that does both happily. Immich's official Compose setup supports acceleration through two small override files; here is how to use them, and how to verify the GPU is actually working.
Published Nov 17, 2026
Two accelerations, two files
Immich's repository ships optional Compose overrides in a hwaccel.transcoding.yml and hwaccel.ml.yml — you enable them by adding them to your docker compose invocation alongside the main file. Transcoding acceleration serves the immich-server; ML acceleration serves the separate immich-machine-learning container, and they are configured independently. The classic pairing on an Intel NAS: Quick Sync for transcoding, OpenVINO for ML — both on the same integrated GPU.
Step 1 — transcoding (Intel Quick Sync)
The override passes the GPU through and selects the driver. Your main Compose gains nothing; you launch with both files:
# hwaccel.transcoding.yml (from the Immich repo, Intel section)
services:
immich-server:
devices:
- /dev/dri:/dev/dri
# VAAPI/QSV selection is finished in the admin UI (step 3)
# launch with the override included:
# docker compose -f docker-compose.yml -f hwaccel.transcoding.yml up -d
Same gotcha as Jellyfin: the container user needs the host's render group. If transcoding silently stays on CPU, check group membership first — our Jellyfin Quick Sync guide explains the render-GID check once, properly, and it applies verbatim here.
Step 2 — machine learning (OpenVINO on Intel, CUDA on NVIDIA)
The ML override swaps the machine-learning image for an accelerated build and passes the GPU to it:
# hwaccel.ml.yml (Intel OpenVINO variant, abridged)
services:
immich-machine-learning:
image: ghcr.io/immich-app/immich-machine-learning:release-openvino
devices:
- /dev/dri:/dev/dri
# NVIDIA instead? Use the CUDA image + the nvidia runtime
# block from the repo's CUDA section of the same file.
First start after enabling this is slow on purpose: the service downloads its models and warms up on your library. Judge it on the second day, when face clustering and smart search run at GPU pace — a library that took a weekend of CPU churn typically finishes its ML backlog in hours.
Step 3 — switch it on in Immich, then verify
- Admin Settings → Video Transcoding: set Hardware Acceleration to Quick Sync (or VAAPI on older chips) and save. Upload a phone video and watch it generate its preview quickly.
- Check the server log during a transcode: it should name the QSV/VAAPI path, not libx264 software encoding.
- For ML: Admin Settings → Machine Learning — confirm the service is reachable, then watch the machine-learning container's log during a library scan for OpenVINO device lines (GPU) instead of CPU-only inference.
- Run a face-heavy test: open Explore after a scan and check people clusters exist. Smart search for something visual ('beach', 'dog') returning sane results is the end-to-end proof.
Troubleshooting
- Everything still on CPU: the override file was not actually included in the compose command, or the container was restarted rather than recreated. Overrides change the container spec; recreate it.
- ML container crash-loops: usually a device path that does not exist on this host (
ls /dev/drion the host first) or an image tag mismatch between server and ML versions — keep both on the same Immich release. - Transcoding works, thumbnails crawl: thumbnail generation is a different job from transcoding and stays CPU-bound; it parallelizes across cores via the job concurrency settings instead.
- NVIDIA GPU not used: the host needs the NVIDIA Container Toolkit and the CUDA variant of the ML override; the OpenVINO image on an NVIDIA host does nothing, quietly.
Sizing expectations: what 'fast' looks like
Numbers set expectations better than adjectives. On a current Intel N-series iGPU, Quick Sync typically transcodes a phone-quality 4K clip several times faster than real time, where the same chip's CPU cores manage roughly real-time on a good day and fall behind on high-bitrate files. OpenVINO face detection on that class of GPU processes a large library's backlog — tens of thousands of photos — in hours rather than the CPU's long weekend, and per-photo smart-search embedding lands in the tens of milliseconds. The point is not the bragging rights; it is that acceleration moves Immich's background jobs from 'a project you schedule around' to 'a thing that is simply done by morning.' If your numbers are nowhere near this after following the steps, treat that as a symptom — the verification steps exist because a silently-unaccelerated Immich looks exactly like a slow one, and the render-group gotcha in step 1 is the cause nine times out of ten.
Official documentation and references
- Immich documentation — hardware-accelerated video transcoding
- Immich documentation — machine-learning hardware acceleration
- Immich documentation — the official docs home
- Immich on GitHub — the official repository and releases
Frequently asked questions
Do I need both accelerations?
No — they are independent. Transcoding matters if your library has lots of video; ML acceleration matters for big photo libraries and face/search features. Most Intel NAS owners enable both because the same GPU does both jobs.
Will hardware acceleration change my photos or videos?
No. Acceleration changes how fast Immich generates previews, thumbnails and ML results — your originals are never modified by either path.
My NAS has no GPU. Is Immich still worth it?
Yes, with patience: CPU transcoding and ML work fine on small libraries, and both jobs can be scheduled for overnight. Acceleration is a quality-of-life multiplier, not a requirement.

