Linuxtools

Jellyfin Hardware Acceleration Setup (Intel QSV/VAAPI)

Prepare a Linux host and container for Jellyfin GPU transcoding: render-node passthrough, the OpenCL runtime for HDR tone-mapping, and how to verify the GPU is doing the work.

DistrosDebian 12, Ubuntu 24.04
Shellbash
Updated
Script
bash
#!/usr/bin/env bash
# Prepare a Debian/Ubuntu host for Jellyfin hardware transcoding on Intel.
# Run on the HOST. NVIDIA users: use the NVIDIA Container Toolkit instead (see Notes).
set -e

# 1) Confirm a GPU render node exists and find the 'render' group ID.
ls -l /dev/dri || { echo "No /dev/dri render node — no usable GPU."; exit 1; }
getent group render || echo "No 'render' group found yet."

# 2) Intel HDR->SDR tone-mapping via OpenCL.
#    (jellyfin-ffmpeg already bundles the QSV/VA-API driver, so no media driver needed here.)
sudo apt-get update
sudo apt-get install -y intel-opencl-icd   # OpenCL for tone-mapping; see Jellyfin's Intel guide for newer-GPU packages

# 3) Native (non-container) install only: let the jellyfin service user reach the GPU.
#    In Docker you instead map the device + add the render group — see Notes.
sudo usermod -aG render,video jellyfin || true

# 4) Enable QSV/VA-API in Dashboard > Playback > Transcoding, then verify a live transcode:
#    Intel:  sudo intel_gpu_top   # Video/Render engines jump while transcoding
#    NVIDIA: nvidia-smi           # your ffmpeg process shows up on the GPU
echo "Host prepared. Enable hardware acceleration in the Jellyfin dashboard, then verify with intel_gpu_top."

What this does

Gets a Linux host ready for Jellyfin hardware transcoding on an Intel iGPU: confirms the GPU render node, installs the OpenCL runtime so HDR→SDR tone-mapping runs on the GPU, and (for a native install) gives the Jellyfin service user access to the video devices. It’s the hands-on companion to Free Hardware Transcoding in Jellyfin. Jellyfin transcodes with jellyfin-ffmpeg, which already bundles the Intel QSV/VA-API driver, so you don’t install a separate media driver — just the OpenCL bits for tone-mapping, per Jellyfin’s Intel guide.

What this stack is for
Everything in this guide automates managing and streaming media you have the rights to — your own rips, DRM-free purchases, home video, Linux ISOs, and public-domain or Creative Commons releases. Downloading copyrighted material you haven't paid for is illegal in most places, and it isn't what this guide teaches. What you point these tools at is on you.

Prerequisites

  • An Intel iGPU that supports the codecs you want (Broadwell / 5th-gen Core or newer for QSV; check the hardware selection guide).
  • Jellyfin installed on a Debian/Ubuntu host or container (install guide).
  • Root/sudo on the host.
  • For NVIDIA instead of Intel, the NVIDIA Container Toolkit and a current driver (522.25+ in the current docs).

Notes

  • Make these values your own before running. Replace jellyfin with your actual Jellyfin service user if it differs, confirm your render node with ls -l /dev/dri (usually /dev/dri/renderD128), and get your host’s render group ID from getent group render (the 122 used below is only an example). If a value looks specific to one machine, it’s a placeholder to change — not a literal to copy.
  • Docker/LXC passthrough. In a container you don’t add the user to a group on the host — you map the device into the container and add the render group by ID:
yaml

services:
jellyfin:
  image: jellyfin/jellyfin
  devices:
    - /dev/dri/renderD128:/dev/dri/renderD128
  group_add:
    - "122"   # your host's render GID from: getent group render
  • NVIDIA is a different path. Don’t map /dev/dri; install the NVIDIA Container Toolkit, expose the GPU to the container (--gpus all or the Compose device reservation), and select NVENC in the dashboard. Tone-mapping on NVIDIA runs through CUDA.
  • Verify, don’t assume. After enabling QSV/VA-API in Dashboard → Playback → Transcoding (tick Enable hardware encoding), start a stream that forces a transcode and watch sudo intel_gpu_top — the Video and Render engines should jump. If the CPU pegs and the GPU stays flat, the passthrough or the codec support is the problem.
  • Only enable codecs your chip can decode. Turning on HEVC or AV1 decoding on an iGPU that lacks it breaks those files instead of accelerating them.
All playbooks