# Docker GPU Passthrough einrichten: NVIDIA-GPU in Docker-Containern nutzen Docker GPU Passthrough bezeichnet die Weitergabe einer NVIDIA-Grafikkarte vom Linux-Host an einen isolierten Docker-Container. Das NVIDIA Container Toolkit bindet dafür die benötigten Gerätedateien und Bestandteile des Host-Treibers über die NVIDIA Container Runtime ein, sodass Anwendungen wie KI-Modelle oder Datenanalysen nahezu ohne zusätzlichen Virtualisierungs-Overhead auf der GPU laufen. Hinweis Diese Anleitung setzt voraus, dass das Linux-System selbst bereits Zugriff auf die NVIDIA-GPU hat. Läuft Docker innerhalb einer virtuellen Maschine, muss die Grafikkarte zunächst durch den Hypervisor an diese virtuelle Maschine weitergegeben werden. Erst danach kann das NVIDIA Container Toolkit sie für Docker-Container bereitstellen. ## Häufige Fehler beim Docker GPU Passthrough
Fehlermeldung oder Problem Wahrscheinliche Ursache Lösung
`nvidia-smi: command not found` Der NVIDIA-Treiber oder das zugehörige Hilfsprogramm ist auf dem Host nicht installiert. Installieren Sie zunächst einen zur Grafikkarte und Linux-Distribution passenden NVIDIA-Treiber. Starten Sie das System anschließend neu.
`NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver` Der Treiber ist nicht richtig geladen. Mögliche Ursachen sind ein fehlender Neustart, ein Kernel-Update oder Probleme mit Secure Boot. Starten Sie das System neu und führen Sie danach erneut `nvidia-smi` aus. Prüfen Sie bei aktiviertem Secure Boot außerdem, ob das NVIDIA-Kernelmodul korrekt signiert und geladen wurde.
`Failed to initialize NVML: Driver/library version mismatch` Die Treiberpakete wurden aktualisiert, während im Kernel noch eine ältere Treiberversion aktiv ist. Starten Sie den Host neu. Dadurch wird das aktualisierte Kernelmodul geladen und an die installierten Treiberbibliotheken angeglichen.
`could not select device driver ... with capabilities: [[gpu]]` Docker kennt die NVIDIA Container Runtime noch nicht oder wurde nach der Konfiguration nicht neu gestartet. Führen Sie `sudo nvidia-ctk runtime configure --runtime=docker` und danach `sudo systemctl restart docker` aus.
`unknown or invalid runtime name: nvidia` Die NVIDIA Runtime wurde nicht in der Docker-Konfiguration registriert. Installieren Sie das NVIDIA Container Toolkit erneut, führen Sie die Runtime-Konfiguration aus und starten Sie Docker neu.
`nvidia-container-cli: requirement error: unsatisfied condition: cuda>=...` Der NVIDIA-Treiber des Hosts ist zu alt für die CUDA-Version des verwendeten Container-Images. Aktualisieren Sie den Host-Treiber oder verwenden Sie ein Container-Image mit einer älteren, zum Treiber passenden CUDA-Version. Deaktivieren Sie die Versionsprüfung nicht dauerhaft.
`E: Conflicting values set for option Signed-By` Auf dem System existieren mehrere alte Einträge für das NVIDIA-Paket-Repository. Suchen Sie mit `grep "nvidia.github.io" /etc/apt/sources.list.d/*` nach doppelten Einträgen und entfernen Sie veraltete Dateien wie `nvidia-docker.list` oder `libnvidia-container.list`.
Docker startet nach einer Änderung nicht mehr Die Datei `/etc/docker/daemon.json` enthält ungültiges JSON oder widersprüchliche Einstellungen. Prüfen Sie die Datei mit `sudo dockerd --validate --config-file=/etc/docker/daemon.json`. Verwenden Sie möglichst `nvidia-ctk`, anstatt die Datei vollständig von Hand zu überschreiben.
`Failed to initialize NVML: Insufficient Permissions` Auf Systemen mit aktiviertem SELinux kann die Sicherheitsrichtlinie den Zugriff blockieren. Prüfen Sie zunächst die SELinux-Protokolle. `--security-opt=label=disable` kann zur Diagnose verwendet werden, schwächt jedoch die Container-Isolation und sollte nicht unkritisch dauerhaft eingesetzt werden.
`Failed to initialize NVML: Unknown Error` bei einem bereits laufenden Container Auf bestimmten Systemen kann ein `systemctl daemon-reload` in Verbindung mit systemd-cgroups den Gerätezugriff laufender Container verändern. Erstellen beziehungsweise starten Sie den betroffenen Container neu. Halten Sie Docker, `runc`, den Treiber und das NVIDIA Container Toolkit aktuell. NVIDIA nennt außerdem CDI oder den cgroupfs-Treiber als mögliche Abhilfen.
Ein **häufiger Irrtum** besteht darin, dass NVIDIA-Treiber und Container Toolkit dieselbe Versionsnummer besitzen müssten. Entscheidend ist vielmehr, dass der Host-Treiber die vom Container benötigte [CUDA](https://www.ionos.at/digitalguide/server/konfiguration/nvidia-cuda/)-Version unterstützt und dass die NVIDIA Runtime korrekt in [Docker](https://www.ionos.at/digitalguide/server/knowhow/was-ist-docker/) eingebunden wurde. ## Schritt 1: Den Linux-Host und den NVIDIA-Treiber vorbereiten Bevor ein [Docker-Container](https://www.ionos.at/digitalguide/server/knowhow/docker-container/) die GPU verwenden kann, muss Linux die Grafikkarte erkennen und ein **funktionsfähiger NVIDIA-Treiber installiert sein**. Das NVIDIA Container Toolkit ersetzt diesen Treiber nicht. Es stellt lediglich die Verbindung zwischen dem vorhandenen Host-Treiber, Docker und dem Container her. Prüfen Sie zunächst, ob das System eine NVIDIA-Grafikkarte erkennt: ```bash lspci | grep -i nvidia ``` Wird eine NVIDIA-GPU angezeigt, prüfen Sie im nächsten Schritt den Treiber: ```bash nvidia-smi ``` Bei einem funktionierenden Treiber erscheint eine **Tabelle mit Informationen** zur Grafikkarte, zur Treiberversion, zum Grafikspeicher und zu den aktuell laufenden GPU-Prozessen. Ist diese Ausgabe bereits vorhanden, können Sie direkt mit Schritt 2 fortfahren. ### NVIDIA-Treiber unter Ubuntu installieren Ubuntu empfiehlt für die automatische Treiberauswahl das Werkzeug `ubuntu-drivers`. Für einen Server oder ein System, das hauptsächlich für [Machine Learning](https://www.ionos.at/digitalguide/online-marketing/web-analyse/was-ist-machine-learning-so-lernen-maschinen-denken/) und andere GPU-Berechnungen verwendet wird, können Sie folgende Befehle ausführen: ```bash sudo apt update sudo apt install -y ubuntu-drivers-common sudo ubuntu-drivers install --gpgpu sudo reboot ``` Bei einer normalen Linux-Workstation mit grafischer Desktop-Oberfläche verwenden Sie stattdessen: ```bash sudo ubuntu-drivers install sudo reboot ``` Das Werkzeug wählt einen Treiber aus, der zur erkannten Hardware und zur Ubuntu-Version passt. Es berücksichtigt außerdem signierte Treiber, was insbesondere bei aktiviertem Secure Boot hilfreich ist. Prüfen Sie die Installation nach dem Neustart erneut: ```bash nvidia-smi ``` Funktioniert `nvidia-smi` auf dem Host nicht, sollten Sie noch nicht mit der Docker-Konfiguration fortfahren. Ein Container kann nur auf eine GPU zugreifen, die bereits vom Host-System korrekt erkannt wird. ### Docker prüfen Kontrollieren Sie außerdem, ob Docker installiert ist und der Docker-Dienst läuft: ```bash docker --version sudo systemctl is-active docker ``` Der zweite Befehl sollte `active` ausgeben. Ist Docker installiert, aber nicht gestartet, aktivieren Sie den Dienst mit: ```bash sudo systemctl enable --now docker ``` ## Schritt 2: NVIDIA-Repository und Container Toolkit installieren Das NVIDIA Container Toolkit besteht aus **mehreren Werkzeugen und Bibliotheken**, die Docker den kontrollierten Zugriff auf die GPU ermöglichen. Die erforderlichen Bestandteile sind im Paket `nvidia-container-toolkit` enthalten. Verwenden Sie nur das stabile NVIDIA-Repository. Das experimentelle Repository ist für eine produktive ML-Ops-Umgebung normalerweise nicht erforderlich. ### Installation mit APT unter Ubuntu oder Debian Installieren Sie zunächst die Programme, die zum Einrichten des [Repositorys](https://www.ionos.at/digitalguide/server/knowhow/repository/) benötigt werden: ```bash sudo apt-get update sudo apt-get install -y --no-install-recommends \ ca-certificates \ curl \ gnupg2 ``` Importieren Sie anschließend den Signaturschlüssel und legen Sie die Paketquelle an: ```bash curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \ | sudo gpg --dearmor \ -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \ | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \ | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list ``` Aktualisieren Sie danach die Paketliste: ```bash sudo apt-get update ``` Installieren Sie nun alle Bestandteile des Toolkits in derselben Version: ```bash export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.0-1 sudo apt-get install -y \ nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION} ``` Durch die feste Versionsangabe werden alle zusammengehörenden Pakete **mit einem einheitlichen Versionsstand** installiert (hier: 1.20.0-1). Hinweis Prüfen Sie bei späteren Updates zunächst die aktuelle Toolkit-Version und passen Sie die Variable anschließend bewusst an. ### Installation mit DNF oder YUM unter RPM-Linux Hinweis Seit RHEL 8 ist Docker **nicht mehr standardmäßig enthalten**. Red Hat setzt stattdessen auf [Podman](https://www.ionos.at/digitalguide/server/tools/podman-tutorial/). Die folgenden Befehle installieren das NVIDIA Container Toolkit, die weitere Anleitung setzt jedoch eine separat eingerichtete Docker Engine voraus. Für aktuelle Versionen von RHEL, Rocky Linux, CentOS, Fedora oder Amazon Linux verwenden Sie in der Regel `dnf`. Installieren Sie zunächst `curl`: ```bash sudo dnf install -y curl ``` Richten Sie danach das NVIDIA-Repository ein: ```bash curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \ | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo ``` Installieren Sie anschließend das Toolkit: ```bash export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.20.0-1 sudo dnf install -y \ nvidia-container-toolkit-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ nvidia-container-toolkit-base-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ libnvidia-container-tools-${NVIDIA_CONTAINER_TOOLKIT_VERSION} \ libnvidia-container1-${NVIDIA_CONTAINER_TOOLKIT_VERSION} ``` Verwendet Ihre Distribution weiterhin den Befehl `yum`, können Sie entsprechend ausführen: ```bash sudo yum install -y nvidia-container-toolkit ``` Tipp NVIDIA testet aktuelle Toolkit-Versionen unter anderem mit RHEL 8, 9 und 10, Ubuntu 22.04, 24.04 und 26.04 sowie ausgewählten Versionen von Rocky Linux, CentOS, Debian und Amazon Linux. Bei anderen Distributionen **kann das Toolkit ebenfalls funktionieren**, sie werden jedoch möglicherweise nicht regelmäßig von NVIDIA getestet. ### Installation kontrollieren Prüfen Sie, ob die zentralen Programme vorhanden sind: ```bash nvidia-ctk --version which nvidia-container-runtime which nvidia-container-cli ``` Die Befehle sollten eine Versionsnummer beziehungsweise einen Programmpfad ausgeben. ## Schritt 3: NVIDIA Runtime in Docker einrichten Nach der Installation kennt Docker die NVIDIA Runtime noch nicht automatisch. Dafür muss die Docker-Daemon-Konfiguration angepasst werden. Verwenden Sie dazu den von NVIDIA bereitgestellten Befehl: ```bash sudo nvidia-ctk runtime configure --runtime=docker ``` `nvidia-ctk` bearbeitet die Datei `/etc/docker/daemon.json` und trägt die NVIDIA Container Runtime dort ein. Der Vorteil gegenüber einer manuellen Bearbeitung besteht darin, dass bereits vorhandene Docker-Einstellungen nicht einfach überschrieben werden. Sie können die Datei anschließend anzeigen: ```bash sudo cat /etc/docker/daemon.json ``` Die genaue Darstellung kann je nach Docker- und Toolkit-Version unterschiedlich aussehen. Entscheidend ist, dass unter den verfügbaren Runtimes ein **Eintrag für `nvidia` vorhanden ist**. Bevor Sie Docker neu starten, können Sie die Konfiguration prüfen: ```bash sudo dockerd --validate --config-file=/etc/docker/daemon.json ``` Bei einer gültigen Datei erscheint: ```none configuration OK ``` Docker bietet diese Prüfung ausdrücklich an, damit Konfigurationsfehler erkannt werden können, bevor der laufende Dienst neu gestartet wird. Starten Sie nun den Docker-Dienst neu: ```bash sudo systemctl restart docker ``` Kontrollieren Sie danach, ob Docker wieder läuft: ```bash sudo systemctl status docker --no-pager ``` Prüfen Sie außerdem die registrierten Runtimes: ```bash docker info | grep -i runtimes ``` In der Ausgabe sollte neben der normalen Runtime `runc` auch `nvidia` erscheinen. Es ist in der Regel **nicht notwendig**, NVIDIA als Standard-Runtime für sämtliche Container festzulegen. Geben Sie die GPU besser nur den Containern frei, die sie tatsächlich benötigen. Dadurch bleibt die Konfiguration nachvollziehbar und normale Webserver-, Datenbank- oder Hilfscontainer erhalten keinen unnötigen Zugriff auf die GPU. Hinweis Aktuelle Versionen des NVIDIA Container Toolkits unterstützen zusätzlich das **standardisierte Container Device Interface (CDI)**. Seit Toolkit-Version 1.18 wird die benötigte CDI-Konfiguration normalerweise automatisch über den Dienst `nvidia-cdi-refresh` erstellt und aktualisiert. Verfügbare GPUs prüfen Sie mit `nvidia-ctk cdi list`. Bei unterstützten Docker-Versionen lässt sich die GPU anschließend beispielsweise mit `--device nvidia.com/gpu=all` an einen Container übergeben. Der in dieser Anleitung beschriebene Zugriff über `--gpus all` funktioniert weiterhin. ## Schritt 4: GPU-Beschleunigung mit nvidia-smi im Container validieren Zum Abschluss starten Sie einen kurzlebigen Testcontainer. Der folgende Befehl gibt dem Container Zugriff auf alle erkannten NVIDIA-GPUs und führt darin `nvidia-smi` aus: ```bash sudo docker run --rm \ --runtime=nvidia \ --gpus all \ ubuntu \ nvidia-smi ``` Docker lädt dabei gegebenenfalls zunächst das Ubuntu-Image herunter. Das NVIDIA Container Toolkit bindet anschließend die benötigten GPU-Geräte und Treiberbibliotheken des Hosts **in den Container ein**. Das Ubuntu-Image selbst muss deshalb keinen vollständigen NVIDIA-Treiber enthalten. NVIDIA verwendet diesen Befehl auch in der offiziellen Beispielkonfiguration. Die Ausgabe sollte ähnlich wie beim Befehl `nvidia-smi` auf dem Host aussehen. Sie sollte mindestens folgende Angaben enthalten: - den Namen der NVIDIA-GPU, - die auf dem Host installierte Treiberversion, - den verfügbaren Grafikspeicher, - die aktuelle GPU-Auslastung - und die vom Treiber unterstützte CUDA-Version. Wichtig ist, dass der Befehl innerhalb des Containers eine GPU anzeigt und nicht mit einer Runtime-, Treiber- oder Berechtigungsfehlermeldung beendet wird. ### Nur eine bestimmte GPU freigeben Besitzt der Host mehrere NVIDIA-GPUs, sollten Sie einem Container **nur die tatsächlich benötigte GPU** zuweisen. Für die erste GPU mit dem Index `0` lautet der Befehl: ```bash sudo docker run --rm \ --runtime=nvidia \ --gpus '"device=0"' \ ubuntu \ nvidia-smi ``` Mehrere ausgewählte GPUs können Sie beispielsweise so freigeben: ```bash sudo docker run --rm \ --runtime=nvidia \ --gpus '"device=0,1"' \ ubuntu \ nvidia-smi ``` Die gezielte Auswahl verhindert, dass ein einzelner Container unbeabsichtigt sämtliche GPU-Ressourcen des Hosts belegt. NVIDIA unterstützt die Auswahl über Geräteindex oder GPU-UUID. ## Best Practices für Docker und NVIDIA-GPUs ### Container-Images eindeutig versionieren Verwenden Sie für produktive Machine-Learning-Anwendungen keine unbestimmten Image-Tags wie `latest`. Geben Sie stattdessen eine konkrete CUDA-, Framework- und Betriebssystemversion an. Dadurch lässt sich später nachvollziehen, welche Softwarestände getestet und eingesetzt wurden. ### Host-Treiber und CUDA-Version aufeinander abstimmen Der NVIDIA-Treiber läuft auf dem Host, während sich die CUDA-Laufzeit **normalerweise im Container** befindet. Der Host-Treiber muss mindestens die Anforderungen des verwendeten CUDA-Images erfüllen. Neuere Treiber können in vielen Fällen ältere CUDA-Anwendungen ausführen, ein zu alter Treiber kann jedoch den Start eines aktuellen CUDA-Containers verhindern. Installieren Sie **nicht** vorsorglich mehrere CUDA-Versionen auf dem Host. Für den normalen Containerbetrieb benötigt der Host vor allem einen funktionierenden NVIDIA-Treiber und das NVIDIA Container Toolkit. ### GPU-Zugriff bewusst begrenzen Verwenden Sie `--gpus all` nur, wenn ein Container wirklich alle Grafikkarten benötigt. In gemeinsam genutzten ML-Ops-Umgebungen ist eine gezielte Zuweisung über `device=0`, eine GPU-UUID oder eine Orchestrierungsplattform besser kontrollierbar. ### Nach Updates erneut testen Führen Sie nach einem Update des Kernels, NVIDIA-Treibers, Docker-Daemons oder NVIDIA Container Toolkits erneut beide Prüfungen aus: ```bash nvidia-smi ``` und: ```bash sudo docker run --rm \ --runtime=nvidia \ --gpus all \ ubuntu \ nvidia-smi ``` Die erste Prüfung testet den Host-Treiber. Die zweite Prüfung testet zusätzlich das Toolkit, die Docker-Konfiguration und die Weitergabe der GPU an den Container. ### Treiberaktualisierungen mit einem Neustart abschließen Nach einem Treiber- oder Kernel-Update kann im laufenden Kernel **weiterhin die alte Version** des NVIDIA-Moduls aktiv sein. Ein geplanter Neustart verhindert Versionskonflikte zwischen Kernelmodul und Treiberbibliotheken. ### daemon.json nicht vollständig überschreiben Enthält `/etc/docker/daemon.json` bereits Einstellungen für Protokollierung, Speicher, Netzwerke oder Registry-Server, dürfen diese nicht verloren gehen. Verwenden Sie deshalb `nvidia-ctk runtime configure` und validieren Sie die Datei vor dem Docker-Neustart mit `dockerd --validate`. ## Fazit Für Docker GPU Passthrough unter Linux werden **drei funktionierende Ebenen** benötigt: ein korrekt installierter NVIDIA-Treiber auf dem Host, das NVIDIA Container Toolkit und eine in Docker registrierte NVIDIA Runtime. Sobald `nvidia-smi` sowohl auf dem Host als auch im Testcontainer funktioniert, steht die GPU für CUDA-, Machine-Learning- und andere rechenintensive Container-Anwendungen zur Verfügung. Durch fest versionierte Container-Images, eine gezielte GPU-Zuweisung und erneute Tests nach Systemupdates bleibt die Konfiguration auch in produktiven ML-Ops-Umgebungen **stabil und nachvollziehbar**. This is a markdown version of: [https://www.ionos.at/digitalguide/server/konfiguration/docker-gpu-passthrough/](https://www.ionos.at/digitalguide/server/konfiguration/docker-gpu-passthrough/) for AI/LLM consumption.