How to Install Docker on Debian for GPU Passthrough and Transcoding

You want buttery-smooth 4K → 1080p hardware transcoding, and the quiet satisfaction of watching your CPU lounge around at 10% while your GPU does the heavy lifting. So you “quickly” pass your GPU into a Docker container… and Jellyfin stares back at you with the enthusiasm of a DMV clerk. The CPU is maxed out. Jellyfin logs throwing a tantrum about “no such device /dev/dri/renderD128.”

Welcome to the club. Population: everyone who has ever tried this.

I once burned a perfectly good Friday night (116 minutes, to be precise) wrestling with what Docker’s documentation cheerfully calls “simple” GPU passthrough. Drivers? Rock solid. Docker daemon? Restarted three times (because why stop at two?). YAML file? Formatted with the precision of a Swiss watchmaker. The actual problem? Linux permissions had decided my container wasn’t ‘special’ enough for the render group’s exclusive party.

After a scenic tour through udev rules, cgroup mysteries, and two spectacularly wrong Reddit threads that shall remain nameless, the GPU finally woke up. Frame times plummeted from “slideshow” to “silk.” My CPU went back to its regularly scheduled napping. And I made myself a solemn promise to document this mess before my brain forgot all the crucial details.

This is that documentation, the step-by-step guide I desperately needed that night. You’ll get the exact Docker Compose configuration, the permissions that actually matter, and a heads-up about the gotchas that love to bite newcomers. Whether you’re running NVIDIA, Intel integrated graphics, or AMD, by the end of this, you’ll have hardware-accelerated transcoding humming along in Docker containers, without the 1 AM debugging session.

💭 TL;DR

Think Docker will magically use your GPU? Cute. NVIDIA needs --gpus, Intel/AMD need /dev/dri, and you need to join the right groups. Otherwise, enjoy watching your CPU sweat bullets.

ASRock Intel ARC A380 Challenger The Arc A380 isn’t for gaming—it’s for obliterating video streams. With support for H.264, HEVC, and full AV1 hardware encode/decode, it crushes 20+ 1080p streams or 6–8 HDR tone-mapped 4Ks without breaking a sweat. Drop it in your media server, give Jellyfin direct VA-API access, and watch your CPU finally cool off for a bit.

Contains affiliate links. I may earn a commission at no cost to you.

Amazon

Why GPU Passthrough Matters

High-quality video transcoding taxes CPUs heavily. Hardware acceleration using GPU features (NVIDIA NVENC, Intel VAAPI/QSV, AMD VCE) speeds this up dramatically, lowering CPU load and noise.

With Docker, you can isolate applications like Jellyfin or Plex in containers while granting them secure, controlled access to the host GPU. This results in smoother streaming, more simultaneous users, quieter fans, and efficient resource use.

Remember, GPU passthrough in Docker differs from VM passthrough. Docker handles device permissions and cgroups, giving containers controlled access to GPUs, and is less complicated than full hardware virtualization.

Why GPU Passthrough in Docker on Debian Often Fails (And How to Fix It)

Here’s the thing about GPU passthrough with Docker on Debian or any other Linux distro: it’s conceptually simple but practically finicky. Your GPU lives on the host system, happily managed by kernel drivers. Your Docker container exists in its own isolated environment with its own filesystem and permissions. Making Docker and your GPU talk requires more than just mounting a device file; you need the right permissions, correct device nodes, and sometimes a few udev rules to harmonize everything.

Think of it like lending your car to a friend. Giving keys (mounting the device) isn’t enough; they need insurance coverage (permissions), know where it’s parked (device paths), and understand the quirks (Linux-specific device behaviors).

Common failures include your container seeing the GPU but lacking permission, missing device nodes causing invisibility, or everything working temporarily, then breaking after a reboot due to unstable device paths.

Let’s fix these and get Docker GPU passthrough working reliably.

Need a Linux permissions refresher?
Understanding Linux Permissions

Proper Docker Compose Configuration for GPU Passthrough on Debian

Forget juggling docker run -it commands with complicated flags. Here’s a straightforward Docker Compose setup for GPU passthrough that persists across Debian reboots:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin-hw
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128  # GPU device access
    group_add:
      - "render"           # Add container user to render group
      - "video"            # Add container user to video group
    environment:
      - JELLYFIN_PublishedServerUrl=http://your-server-ip:8096
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /path/to/media:/media:ro
    ports:
      - "8096:8096"
    restart: unless-stopped

Why this works:

devices: /dev/dri:/dev/dri exposes all GPU device nodes, essential for hardware transcoding.
group_add adds your container user to render and video groups, granting necessary permissions.
restart: unless-stopped ensures resilience on Debian system reboots.

NVIDIA vs Intel/AMD GPU Passthrough on Docker

NVIDIA: Simplified GPU Passthrough

Install the proprietary NVIDIA driver and NVIDIA Container Toolkit on Debian. Use docker run -it --gpus all or Docker Compose device_requests for straightforward passthrough. The NVIDIA Toolkit handles driver mapping and permissions automatically.

This is suitable for Transcoding, AI, or other CUDA workloads

Intel/AMD: Manual Device Mapping

For Intel and AMD on Debian, manually expose /dev/dri into containers, manage permissions carefully, and ensure correct drivers (intel-media-driver, mesa-va-drivers) are installed.

Add container users to render and video groups to avoid permission denied errors. This approach is rock-solid for media transcoding workloads.

Preparing Your Debian Host for Docker GPU Passthrough

Before installing Docker and configuring containers, confirm your GPU works on Debian host:

NVIDIA Setup on Debian

Install NVIDIA proprietary drivers. Verify with nvidia-smi.
Install NVIDIA Container Toolkit:

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Verify with:

docker run --rm --gpus=all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Intel iGPU Setup

Confirm i915 kernel driver loaded:

lsmod | grep i915

Check /dev/dri device nodes exist.
Install VA-API drivers:

sudo apt install intel-media-va-driver vainfo

Verify working with vainfo.

Docker and Docker Compose Requirements for GPU Passthrough on Debian

Docker version 20.10+ (check with docker --version)
Docker Compose V2 (docker compose command, not the legacy docker-compose)
Linux kernel with cgroup v2 enabled

NVIDIA users require proper runtime configuration via nvidia-container-toolkit. Intel/AMD users need only proper device mapping and permissions.

Correct GPU Passthrough Configuration with Docker Compose on Debian

⚠️

Warning: I do not use NVIDIA or AMD hardware in my lab. Everything NVIDIA or AMD related in this post is straight from the documention.

NVIDIA Compose Example:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    ports:
      - "8096:8096"
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/media:/media
    restart: unless-stopped
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Intel/AMD Compose Example:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128
    user: "1000:1000"  # Adjust to your host user UID:GID
    group_add:
      - "render_gid"    # Replace with actual host render group GID
      - "video_gid"     # Replace with actual host video group GID
    ports:
      - "8096:8096"
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/media:/media
    restart: unless-stopped

Sparkle Intel Arc B580 Titan The Intel Arc B580 is a transcoding powerhouse, with full hardware support for AV1, HEVC, VP9, and H.264 plus 12 GB of VRAM for smooth multi-stream 4K/8K workflows. Its 160 XMX AI engines turbocharge upscaling and media conversions, making it perfect for Plex, Jellyfin, or Docker-based media servers.

Contains affiliate links. I may earn a commission at no cost to you.

Amazon Newegg

Resolving Common GPU Passthrough Issues on Debian with Docker

“no available runtime” or “could not select device driver” indicates missing NVIDIA Container Toolkit.
“no such device /dev/dri/renderD128” means device nodes not mapped or GPU drivers missing.
Permission denied errors usually stem from missing group_add for render and video groups.
Use udev rules to make permissions persistent across reboots.

Verifying GPU Access Inside Your Docker Container

For NVIDIA: Run docker run --rm --gpus=all nvidia/cuda nvidia-smi.
For Intel/AMD: Run docker run --rm --device /dev/dri:/dev/dri jrottenberg/ffmpeg ffmpeg -hwaccels and look for vaapi or qsv.

Real-World Example: Jellyfin GPU Passthrough on Debian

NVIDIA-enabled Jellyfin:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/media:/media
    ports:
      - "8096:8096"
    restart: unless-stopped
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Intel iGPU Jellyfin:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128
    user: "1000:1000"
    group_add:
      - "render_gid"
      - "video_gid"
    volumes:
      - /srv/jellyfin/config:/config
      - /srv/media:/media
    ports:
      - "8096:8096"
    restart: unless-stopped

Final Tips for Installing Docker on Debian and Running GPU Passthrough on Raspberry Pi and Home Servers

Always start by verifying GPU functionality on the host Linux system.
Install Docker on Debian using the official repositories or Docker’s install script.
- My Docker install instructions
Use docker run -it with --gpus for quick NVIDIA GPU container testing.

With these steps, you can enjoy hardware-accelerated transcoding and efficient GPU usage inside Docker containers on Linux.

Other Resources

Happy transcoding with Docker!

Intel NUC 12 Pro (NUC12WSHi5) Compact mini PC for lightweight servers, GPU Passthrough, Docker stacks, and VMs.

Contains affiliate links. I may earn a commission at no cost to you.

Amazon Newegg