.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Immich hardware acceleration is two separate features wearing one name, and most guides blur them together. Video transcoding acceleration uses a GPU's encoder block to convert your videos without cooking the CPU. Machine-learning acceleration runs the search and face models on GPU compute, turning an overnight indexing pass into an hour. Different compose files, different hardware requirements, different payoffs. Here's both, plus the judgment call on which (if either) your library needs.
When hardware acceleration is worth it
CPU does everything Immich needs, just slower. The jobs that justify acceleration are specific: a large video collection getting transcoded (thousands of clips, or 4K sources), the initial ML indexing of six-figure photo counts, or re-running that indexing when a model change makes the jobs come back. A ten-thousand-photo library on a 4 vCPU box indexes overnight on CPU and then rarely thinks about it again. My general advice: install plain, watch Administration » Jobs during the first big index, and reach for acceleration only if the queue's pace offends you. Steady-state Immich after indexing is a light app.
Supported hardware: NVENC, QSV, VAAPI and CUDA
The transcoding side supports NVENC (NVIDIA), Quick Sync (Intel iGPUs, the self-hosting community's darling for efficiency), VAAPI (the generic Linux path, AMD included) and RKMPP (Rockchip SBCs). The ML side is narrower in practice, with CUDA on NVIDIA as the mainstream option and OpenVINO covering Intel. On a home box with an Intel chip, QSV for video is the classic cheap win. On rented infrastructure the calculus is simpler: standard VPS instances have no GPU, so acceleration means a GPU-equipped machine, full passthrough being the arrangement that lets containers see real hardware, which is how our GPU VPS line is built. For most photo-first libraries, renting GPU permanently for Immich alone is overkill; the sane pattern is doing the heavy initial index on strong hardware, or accepting the overnight CPU pass, and only keeping GPU where video transcoding is a running concern.
Enable hardware transcoding
Immich ships the wiring as an extra compose file, per the official hardware transcoding docs. Download the release's hwaccel.transcoding.yml next to your compose file, then extend the server service in docker-compose.yml with your backend:
services:
immich-server:
extends:
file: hwaccel.transcoding.yml
service: quicksync # or nvenc, vaapi, rkmppNVIDIA additionally needs the container toolkit installed on the host so Docker can hand the GPU to containers; Intel and VAAPI setups mostly need /dev/dri present and the container's user able to touch it. Recreate the stack (docker compose up -d), then flip the software switch people forget: Administration » Settings » Video Transcoding » hardware acceleration, select the same backend. Compose wiring without this setting does exactly nothing, and this pairing (device plumbed AND setting selected) is the number one gap in failed setups.
Enable hardware-accelerated machine learning
Same pattern, sibling file: hwaccel.ml.yml, extending the machine-learning service instead:
services:
immich-machine-learning:
extends:
file: hwaccel.ml.yml
service: cuda # or openvino
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cudaNote the image tag change: the ML container has hardware-specific builds, and the tag suffix must match the service you extended (the docs table maps them). After recreating, the payoff shows wherever the ML queues run: smart search indexing, face detection and facial recognition jobs all move several times faster. To make existing assets benefit, re-queue those jobs from Administration » Jobs; acceleration only touches work done after it's enabled.
Verify GPU usage during jobs
Trust measurements, not settings pages. For transcoding: queue a video transcode job and watch the encoder. On NVIDIA, nvidia-smi on the host shows the ffmpeg process and encoder utilization; on Intel, intel_gpu_top shows the video engine working. CPU staying calm while videos convert is the visible symptom. For ML: run the smart search job on a batch and compare the items-per-second against your CPU baseline; the difference is not subtle when CUDA is truly engaged, and docker compose logs immich-machine-learning states the loaded execution provider at startup, naming CUDA or OpenVINO explicitly.
When it doesn't work, the failure map is short. Transcodes erroring after enabling acceleration: the backend doesn't match the hardware or the device never reached the container, and Immich's fallback toggle (allow software fallback in the same settings page) keeps the library functional while you debug. ML container crash-looping on the CUDA image: driver and toolkit versions disagree, check nvidia-smi works inside a plain test container first. And a failed transcode pipeline generally shows up as gray tiles and broken video previews, which loops you into the diagnosis path of our error loading image guide; run its checks with the acceleration settings in mind and the culprit surfaces quickly. Enabled, verified and load-tested once, the whole feature disappears into the background, exactly like it should.
