Docker GPU-Unterstützung: NVIDIA Container Toolkit

Was dieser Artikel über Docker GPU behandelt

• Wie Du das NVIDIA Container Toolkit installierst und Docker für GPU-Zugriff konfigurierst
• Wie Du mit --gpus all die GPU an einen Container durchreichst
• Wie Du GPU-Support in docker-compose über deploy.resources aktivierst
• Wie Du Ollama mit GPU-Beschleunigung in Docker startest
• Welche Stolpersteine es bei Treibern, Runtime und Compose-Dateien gibt

Einleitung: Docker GPU verständlich erklärt

Docker isoliert Anwendungen in Containern. Standardmäßig bekommt ein Container keinen Zugriff auf die Grafikkarte Deines Host-Systems. Für reine CPU-Workloads ist das kein Problem. Sobald Du aber KI-Modelle, Video-Encoding oder CUDA-basierte Berechnungen in einem Container ausführen willst, brauchst Du die GPU. Genau hier kommt das NVIDIA Container Toolkit ins Spiel.

Das Toolkit ist eine Erweiterung für Docker, die den NVIDIA-Treiber des Host-Systems in Container durchreicht. Du installierst es einmal, konfigurierst die Docker-Runtime und kannst danach jedem Container mit dem Parameter --gpus all die GPU übergeben. Im Container steht dann nvidia-smi zur Verfügung, und CUDA-Anwendungen laufen mit voller GPU-Beschleunigung.

Dieser Artikel führt Dich Schritt für Schritt durch die Installation auf Ubuntu, das Testen der GPU in einem Container und die Einrichtung von Ollama mit GPU-Support. Wenn Du Docker noch nicht kennst, lies zuerst die Docker Grundlagen. Einen Überblick über das Thema Self-Hosting findest Du unter Self-Hosting.

Warum brauche ich GPU in Docker?

Stell Dir vor, Du betreibst Ollama in einem Docker-Container auf Deinem Server. Ohne GPU-Support läuft das Modell auf der CPU. Ein 7B-Modell wie Llama 3 braucht auf einer modernen CPU etwa 30 bis 60 Sekunden für die ersten Token und danach wenige Token pro Sekunde. Ein Chat ist damit kaum nutzbar.

Mit GPU sieht das ganz anders aus. Eine NVIDIA-GPU mit 8 GB VRAM generiert beim gleichen Modell 30 bis 60 Token pro Sekunde, die ersten Tokens erscheinen in unter einer Sekunde. Der Unterschied ist massiv. Mehr zum Vergleich findest Du im Artikel CPU vs. GPU und unter GPU-Offloading.

Damit Ollama in Docker die GPU nutzen kann, musst Du die Grafikkarte in den Container durchreichen. Das nennt man GPU Passthrough. Dafür brauchst Du das NVIDIA Container Toolkit, das die Brücke zwischen Host-Treiber und Container schlägt. Ohne dieses Toolkit sieht der Container keine GPU, egal welche Parameter Du übergibst.

Docker GPU kurz erklärt

Du installierst das NVIDIA Container Toolkit, konfigurierst die Docker-Runtime mit nvidia-ctk runtime configure --runtime=docker und startest Docker neu. Danach übergibst Du jedem Container, der GPU-Zugriff braucht, den Parameter --gpus all. In docker-compose nutzt Du dafür den Block deploy.resources.reservations.devices mit dem Driver nvidia. Im Container prüfst Du mit nvidia-smi, ob die GPU erkannt wird.

Für wen ist dieser Artikel gedacht?

Dieser Artikel richtet sich an alle, die GPU-beschleunigte Workloads in Docker-Containern ausführen wollen. Das sind Self-Hoster, die Ollama oder andere KI-Tools auf einem Server mit NVIDIA-GPU betreiben. Das sind Entwickler, die CUDA-Anwendungen in Containern testen und deployen. Und das sind Administratoren, die mehrere GPU-Dienste auf einer Maschine isoliert verwalten wollen.

Wenn Du Docker noch nie genutzt hast, starte mit den Docker Grundlagen. Wenn Du Ollama noch nicht kennst, lies zuerst die Ollama Übersicht.

Wichtige Begriffe

Begriff	Bedeutung
NVIDIA Container Toolkit	Software-Paket, das NVIDIA-GPUs in Docker-Containern verfügbar macht
nvidia-smi	Kommandozeilen-Tool, das GPU-Status, VRAM und Prozesse anzeigt
CUDA	NVIDIA-Plattform für parallele Berechnungen auf der GPU
Docker Runtime	Komponente, die Container startet und verwaltet, erweiterbar durch GPU-Unterstützung
—gpus	Docker-Parameter, der eine oder mehrere GPUs an einen Container übergibt
GPU Passthrough	Durchreichen der physischen GPU an einen Container oder eine VM
Container	Isolierte Laufzeitumgebung, die ein Image mit allen Abhängigkeiten ausführt
VRAM	Videospeicher der GPU, in dem Modelle und Zwischenergebnisse liegen
Driver	NVIDIA-Treiber auf dem Host-System, Voraussetzung für GPU-Zugriff
Runtime	Ausführungsumgebung, in Docker über nvidia-ctk konfigurierbar

Voraussetzungen

Bevor Du startest, brauchst Du zwei Dinge auf Deinem Host-System:

1. Ein funktionierender NVIDIA-Treiber. Prüfe mit nvidia-smi auf dem Host, ob die GPU erkannt wird:

nvidia-smi

Wenn Du eine Tabelle mit GPU-Name, Treiber-Version und VRAM siehst, ist der Treiber korrekt installiert. Fehlt das Kommando oder erscheint eine Fehlermeldung, installiere zuerst den NVIDIA-Treiber. Auf Ubuntu geht das mit:

sudo ubuntu-drivers autoinstall
sudo reboot

2. Docker installiert. Prüfe die Docker-Version:

docker --version

Wenn Docker fehlt, installiere es über den offiziellen Installer. Eine Anleitung findest Du in den Docker Grundlagen und im Artikel zu Ubuntu.

NVIDIA Container Toolkit installieren

Die Installation läuft auf Ubuntu in wenigen Schritten ab. Du fügst das NVIDIA-Repository hinzu, installierst das Paket und konfigurierst die Docker-Runtime.

Schritt 1: Repository-Schlüssel hinzufügen

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

Schritt 2: Repository eintragen

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

Schritt 3: Paket installieren

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Schritt 4: Docker-Runtime konfigurieren

sudo nvidia-ctk runtime configure --runtime=docker

Dieser Befehl trägt die NVIDIA-Runtime in die Docker-Konfiguration ein. Du kannst das überprüfen:

cat /etc/docker/daemon.json

Die Datei sollte einen Eintrag für nvidia als Default-Runtime oder als benannte Runtime enthalten.

Schritt 5: Docker neu starten

sudo systemctl restart docker

Damit übernimmt Docker die neue Konfiguration. Ab jetzt kannst Du Containern die GPU übergeben.

Docker mit GPU testen

Nach der Installation testest Du, ob die GPU in einem Container erreichbar ist. Dafür nutzt Du das offizielle CUDA-Image von NVIDIA:

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

Wenn im Output die GPU-Tabelle erscheint, ist alles korrekt eingerichtet. Der Container hat Zugriff auf die Grafikkarte.

Du kannst auch gezielt eine bestimmte GPU übergeben, falls Du mehrere hast:

docker run --rm --gpus '"device=0"' nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Der Parameter '"device=0"' wählt die erste GPU aus. Mit '"device=0,1"' übergibst Du zwei GPUs.

Ollama mit GPU in Docker

Ollama profitiert enorm von GPU-Beschleunigung. Mit dem installierten Toolkit startest Du Ollama mit GPU-Support:

docker run -d --gpus all --name ollama-gpu -p 11434:11434 -v ollama-data:/root/.ollama ollama/ollama

Die einzelnen Parameter bedeuten:

• -d: Startet den Container im Hintergrund
• --gpus all: Übergibt alle GPUs an den Container
• --name ollama-gpu: Container-Name für einfache Referenz
• -p 11434:11434: Port Mapping für die Ollama-API
• -v ollama-data:/root/.ollama: Volume für Modellpersistenz

Prüfe, ob die GPU im Container erkannt wird:

docker exec -it ollama-gpu nvidia-smi

Wenn die GPU-Tabelle erscheint, nutzt Ollama die Grafikkarte. Mehr zu Ollama mit Docker findest Du im Artikel Ollama mit Docker.

docker-compose mit GPU

Für reproduzierbare Setups nutzt Du docker-compose. Die GPU-Konfiguration erfolgt über den deploy.resources-Block.

Erstelle eine Datei docker-compose.yml:

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-gpu
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama-data:

Starte den Container:

docker compose up -d

Der deploy.resources.reservations.devices-Block teilt Docker mit, dass der Container eine NVIDIA-GPU braucht. Der Eintrag count: all übergibt alle GPUs. Mit count: 1 übergibst Du genau eine. Die capabilities: [gpu] markieren den Gerätetyp.

In älteren Docker-Versionen wurde runtime: nvidia verwendet. Das funktioniert in aktuellen Versionen nicht mehr zuverlässig. Nutze stattdessen den deploy-Block.

Beispiel: Ollama GPU in Docker

Hier ein komplettes Beispiel von der Installation bis zum laufenden Modell.

Schritt 1: Toolkit installieren (wie oben beschrieben)

Schritt 2: docker-compose.yml erstellen

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-gpu
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama-data:

Schritt 3: Container starten

docker compose up -d

Schritt 4: GPU im Container prüfen

docker exec -it ollama-gpu nvidia-smi

Schritt 5: Modell laden

docker exec -it ollama-gpu ollama pull llama3

Schritt 6: Modell starten

docker exec -it ollama-gpu ollama run llama3

Der Chat öffnet sich im Terminal. Die GPU-Beschleunigung sorgt für schnelle Antworten. Mit /bye beendest Du die Sitzung.

Typische Stolpersteine

GPU wird im Container nicht erkannt. Meist fehlt die Runtime-Konfiguration oder Docker wurde nicht neu gestartet. Prüfe mit nvidia-smi auf dem Host und mit docker exec -it ollama-gpu nvidia-smi im Container. Wenn es auf dem Host funktioniert, im Container aber nicht, fehlt nvidia-ctk runtime configure --runtime=docker oder der Docker-Neustart.

NVIDIA-Treiber veraltet. Das Toolkit braucht einen kompatiblen Treiber. Wenn Dein Treiber zu alt ist, schlägt die Installation fehl oder nvidia-smi funktioniert im Container nicht. Aktualisiere den Treiber und starte neu.

--gpus wird nicht erkannt. Dieser Parameter existiert erst ab Docker 19.03. Wenn Du eine ältere Version nutzt, aktualisiere Docker. Prüfe mit docker --version.

docker-compose ignoriert GPU-Einstellungen. In aktuellen Docker-Versionen funktioniert runtime: nvidia nicht mehr. Nutze den deploy.resources.reservations.devices-Block. Stelle sicher, dass Du docker-compose v2 nutzt, nicht die alte Python-Version.

Container läuft, aber CUDA-Anwendung stürzt ab. Manchmal fehlen CUDA-Bibliotheken im Container. Nutze ein Image, das CUDA bereits enthält, beispielsweise nvidia/cuda:12.4.0-base-ubuntu22.04, oder installiere CUDA im Dockerfile.

VRAM reicht nicht aus. Große Modelle brauchen viel VRAM. Wenn die GPU zu wenig Videospeicher hat, bricht die Anwendung ab oder stürzt in den CPU-Modus zurück. Prüfe den VRAM-Verbrauch mit nvidia-smi während das Modell läuft. Mehr dazu unter GPU-Offloading.

Mehrere Container teilen sich eine GPU. Wenn mehrere GPU-Container gleichzeitig laufen, teilen sie sich den VRAM. Das kann zu OOM-Fehlern führen. Überwache den VRAM mit nvidia-smi und verteile Workloads auf mehrere GPUs oder starte Container nacheinander.

Hardware, Kosten und Sicherheit

Hardware: Du brauchst eine NVIDIA-GPU mit ausreichend VRAM. Für 7B-Modelle reichen 8 GB VRAM, für 13B-Modelle 12 bis 16 GB, für 70B-Modelle deutlich mehr. Der Host braucht genug RAM und CPU, um den Container und das Betriebssystem zu tragen. Mehr zu Hardware-Entscheidungen unter CPU vs. GPU.

Kosten: Das NVIDIA Container Toolkit ist kostenlos und Open Source. Docker ist ebenfalls kostenlos. Kosten entstehen ausschließlich durch die Hardware, also GPU, Server und Strom. Es fallen keine Lizenzgebühren an.

Sicherheit: GPU-Passthrough gibt dem Container vollen Zugriff auf die GPU. Das ist kein Sicherheitsrisiko für den Host, solange Du vertrauenswürdige Images nutzt. Achte darauf, dass Du nur offizielle Images von Docker Hub oder vertrauenswürdigen Quellen einsetzt. Wenn Du mehrere Nutzer auf einem Server hast, sollten GPU-Container nicht ungeschützt im Netzwerk erreichbar sein. Nutze Firewall-Regeln und, wenn möglich, ein VPN wie Tailscale für den Remote-Zugriff.

Weiterführende Links

• Self-Hosting für einen Überblick über das Thema
• Docker Grundlagen für den Einstieg in Docker
• Ollama mit Docker für Ollama-spezifische Docker-Konfiguration
• Ollama Übersicht für einen allgemeinen Einstieg
• CPU vs. GPU für den Vergleich von CPU- und GPU-Betrieb
• GPU-Offloading für Details zum GPU-Einsatz
• Ubuntu für Grundlagen zum Betriebssystem

FAQ: Docker GPU-Unterstützung

Brauche ich das NVIDIA Container Toolkit für AMD-GPUs?

Nein. Das Toolkit ist spezifisch für NVIDIA. Für AMD-GPUs nutzt Du den ROCm-Stack und übergibst die GPU über --device /dev/kfd und --device /dev/dri. Die Konfiguration unterscheidet sich deutlich von NVIDIA.

Funktioniert GPU-Support auch ohne NVIDIA-Treiber auf dem Host?

Nein. Das Toolkit reicht den Host-Treiber in den Container durch. Ohne funktionierenden NVIDIA-Treiber auf dem Host gibt es keine GPU im Container. Installiere zuerst den Treiber und prüfe mit nvidia-smi auf dem Host.

Kann ich mehrere GPUs auf verschiedene Container aufteilen?

Ja. Mit --gpus '"device=0"' übergibst Du nur die erste GPU, mit '"device=1"' die zweite. In docker-compose nutzt Du count: 1 und ergänzt device_ids: [0] im Device-Block.

Was bedeutet capabilities: [gpu] in docker-compose?

Der Eintrag markiert den Gerätetyp, den der Container braucht. gpu ist der Standard für GPU-Zugriff. Du kannst auch compute, utility, graphics oder video angeben, wenn Du spezifische CUDA-Funktionen brauchst.

Funktioniert GPU-Support auf Windows mit Docker Desktop?

Ja, mit WSL2-Backend und den passenden NVIDIA-Treibern für WSL. Der Parameter --gpus all funktioniert wie auf Linux. Auf macOS mit Apple Silicon wird die GPU über Metal bereitgestellt, das Toolkit wird dort nicht benötigt.

Wie sehe ich, wie viel VRAM mein Container nutzt?

Führe nvidia-smi auf dem Host aus, während der Container läuft. Die Tabelle zeigt alle Prozesse, die GPU-Ressourcen nutzen, mit ihrem VRAM-Verbrauch. Alternativ nutzt Du docker exec -it ollama-gpu nvidia-smi im Container.

Muss ich Docker neu starten, wenn ich den NVIDIA-Treiber aktualisiere?

Ja. Nach einem Treiber-Update starte den Host neu oder zumindest den Docker-Dienst mit sudo systemctl restart docker. Sonst kann der Container auf eine veraltete Treiber-Version zugreifen.

Kann ich GPU-Support nachträglich aktivieren, ohne den Container neu zu erstellen?

Nein. Der Parameter --gpus wird beim Start eines Containers festgelegt. Du musst den Container stoppen, entfernen und mit --gpus all neu starten. Das Volume sichert Deine Daten.

Was ist der Unterschied zwischen --gpus all und runtime: nvidia?

--gpus all ist der aktuelle Standard ab Docker 19.03. runtime: nvidia war der frühere Weg und gilt als veraltet. In docker-compose nutzt Du den deploy.resources-Block, nicht die Runtime-Zeile.

Brauche ich CUDA im Container, wenn ich das Toolkit installiert habe?

Das hängt von Deiner Anwendung ab. Das Toolkit reicht den Treiber durch, aber CUDA-Bibliotheken müssen im Image vorhanden sein. Bei Ollama sind sie im Image enthalten. Bei eigenen Anwendungen nutze ein CUDA-Image oder installiere CUDA im Dockerfile.

Kann ich Ollama mit GPU in Docker auf einem NAS betreiben?

Ja, wenn das NAS eine NVIDIA-GPU hat und Linux-basiert ist, beispielsweise ein Ugreen- oder Asrock-Gerät. Synology-NAS nutzen meist Intel oder AMD und unterstützen das NVIDIA Container Toolkit nicht direkt. Prüfe die Hardware-Unterstützung Deines NAS.

Quellen

• NVIDIA Container Toolkit Dokumentation: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/
• Docker GPU-Dokumentation: https://docs.docker.com/config/containers/resource_constraints/#gpu
• NVIDIA CUDA Docker Images: https://hub.docker.com/r/nvidia/cuda
• Ollama Docker Image: https://hub.docker.com/r/ollama/ollama