Generate Plex preview thumbnails with a GPU (NVIDIA, Intel, AMD)

Generate Plex video preview thumbnails with NVIDIA, Intel or AMD in Docker. Check GPU passthrough, mounts, CPU fallback and the first result.

Plex's built-in preview thumbnail generator documents no GPU option. Plex describes it as a CPU-intensive job. To make Plex's preview thumbnails on a GPU, run Media Preview Generator in Docker and pass the GPU through:

NVIDIA: --gpus all with NVIDIA_DRIVER_CAPABILITIES=all.
Intel or AMD: --device /dev/dri.

It decodes each video with FFmpeg on the GPU and writes the BIF file into Plex's data folder. Plex then serves it as if Plex had made it. GPU acceleration works on Linux hosts, and on Windows for NVIDIA only.

Plex's web player mid-scrub, showing a preview thumbnail this app made

Plex's web player on a test server. Tears of Steel, (CC) Blender Foundation | mango.blender.org, CC BY 3.0.

What's supported

Linux: NVIDIA (CUDA), Intel (VAAPI, the QuickSync hardware) and AMD (VAAPI).
Windows (Docker Desktop, WSL2 backend): NVIDIA only. AMD and Intel GPUs can't be reached from Docker's Linux VM, so those setups run on CPU.
macOS: no GPU acceleration under Docker. It runs on CPU, using the native ARM64 image on Apple Silicon.
No GPU: add a CPU worker group in Settings → Workers.
Several GPUs: add each GPU as a device in a worker group in Settings → Workers. A group has a name and hours, and each device in it has a worker count (1–64) and the jobs it may run. Settings → Processing options → GPU device tuning lists each detected GPU with its FFmpeg threads per worker.
A GPU in another machine: add that machine as a worker node.

Details and caveats are in Getting Started — GPU Acceleration.

Run it

Intel or AMD:

docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  -p 8080:8080 \
  --device /dev/dri:/dev/dri \
  -e PUID=1000 -e PGID=1000 \
  -v /path/to/media:/media:ro \
  -v "/path/to/Plex Media Server":/plex \
  -v /path/to/app/config:/config \
  stevezzau/media_preview_generator:latest

NVIDIA: install the NVIDIA Container Toolkit on Linux (Docker Desktop on Windows provides it). Then replace the --device line with:

  --gpus all \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=all \

Use all, not compute,video,utility. The graphics capability that all includes loads NVIDIA's Vulkan driver into the container. Dolby Vision Profile 5 thumbnails need it. See HDR and Dolby Vision thumbnails.

For Docker Compose, Unraid and permission problems with /dev/dri, see:

What Plex needs

Plex's data folder, mounted read-write at /plex. This is the folder that contains Cache, Media and Metadata. BIFs are written inside it, at Media/localhost/<h>/<hash>.bundle/Contents/Indexes/index-sd.bif. A read-only mount blocks every write. The Plex config folder check in Setup Health tells you if it's wrong.
The media, visible to the container. Read-only is fine for Plex, because nothing is written next to the video.
Path mappings if Plex and the container see the media at different paths. See Path Mappings.
Plex's own generation off. Set Settings → Library → Generate video preview thumbnails to Never, so Plex doesn't redo the work.

Then open http://YOUR_IP:8080, log in with the token saved in auth.json in your app config folder (or your own, set with WEB_AUTH_TOKEN), and sign in to Plex in the setup wizard.

Check the GPU is being used

Settings → Workers offers every GPU the container found, and GPU device tuning lists them with name and type. If yours isn't there, the container can't see it. Check the --device or --gpus flag, then the troubleshooting table.
Start a job and watch the Workers panel on the dashboard. Each worker group has its own card. A yellow CPU fallback badge means no GPU could do that file, so the CPU did. The job log says why (CPU fallback). If several files in a row fall back, the bell menu flags the GPU.
On the host, while a job runs, look for FFmpeg processes. On NVIDIA, nvidia-smi lists processes using the GPU. On Intel, intel_gpu_top (from intel-gpu-tools) shows video engine load.

Verify one file before a full library

Use Process a file or folder on the Dashboard to choose one movie or episode. Watch the Workers panel, then open the job's Job details from the jobs list. The server results distinguish generated or reused scrubber previews from chapter work. Open Open logs and files for the file's saved result or error, and scrub the same video in Plex to check the preview appears. A completed extraction is not the same as successful publication to every server.

For a separate GPU machine, first check the shared-media and output mounts in Offload preview generation.

Tuning

Start with one worker in the GPU's group, then raise it while watching load. See Worker Configuration.
FFmpeg threads per worker (default 2, 0 = no cap) caps the CPU threads each worker on that GPU may use. Lower it if CPU is the bottleneck.
Settings → Processing options → Thumbnail interval defaults to 10 seconds (1–60). Plex's own documented default is 2 seconds. Fewer frames means less work.
On unRAID, mergerfs or JBOD shares, set Processing Order → Random when you start a full scan or create a schedule. Workers then read from different disks (FAQ).

Limits

Docker only, with a web UI and no CLI.
File/folder jobs and path-based webhooks can generate previews before Plex scans a file, including while Plex is offline. Publication and Plex's ability to serve the result still depend on the file's server state; see generation without waiting for Plex. Work that must wait for indexing uses the retry queue.
GPU acceleration applies to scrubber previews. Optional chapter thumbnails use CPU, are off by default, and currently support Plex 1.43.4.x or 1.43.5.x.

Edit this page on GitHub