Docker-Schnellstartanleitung für Ultralytics#

Diese Anleitung bietet eine umfassende Einführung in die Einrichtung einer Docker-Umgebung für deine Ultralytics-Projekte. Docker ist eine Plattform zum Entwickeln, Bereitstellen und Ausführen von Anwendungen in Containern. Sie ist besonders nützlich, um sicherzustellen, dass die Software unabhängig vom Bereitstellungsort immer gleich ausgeführt wird. Weitere Informationen findest du im Ultralytics-Docker-Repository auf Docker Hub.

Das lernst du#

• Docker mit NVIDIA-Unterstützung einrichten
• Ultralytics-Docker-Images installieren
• Ultralytics in einem Docker-Container mit CPU- oder GPU-Unterstützung ausführen
• Einen Anzeigeserver mit Docker verwenden, um Ultralytics-Erkennungsergebnisse anzuzeigen
• Lokale Verzeichnisse in den Container einbinden

Voraussetzungen#

• Stelle sicher, dass Docker auf deinem System installiert ist. Falls nicht, kannst du Docker von der Docker-Website herunterladen und installieren.
• Für die GPU-Beschleunigung benötigst du eine NVIDIA-GPU und installierte NVIDIA-Treiber. Für CPU-Images ist keine NVIDIA-Hardware erforderlich.
• Wenn du NVIDIA Jetson-Geräte verwendest, stelle sicher, dass die passende JetPack-Version installiert ist. Weitere Informationen findest du in der NVIDIA-Jetson-Anleitung.

Docker mit NVIDIA-Unterstützung einrichten (optional)#

Prüfe zunächst mit folgendem Befehl, ob die NVIDIA-Treiber ordnungsgemäß installiert sind:

nvidia-smi

NVIDIA Container Toolkit installieren#

Installieren wir nun das NVIDIA Container Toolkit, um GPU-Unterstützung in Docker-Containern zu aktivieren:

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

sudo apt-get update

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

CDI-Geräte mit Docker überprüfen#

Führe nvidia-ctk cdi list aus, um sicherzustellen, dass die GPU-CDI-Geräte verfügbar sind (der Dienst nvidia-cdi-refresh des Toolkits erstellt und verwaltet die Spezifikation ab Toolkit-Version >= 1.18 automatisch):

nvidia-ctk cdi list

Es sollten Einträge wie nvidia.com/gpu=0 und nvidia.com/gpu=all angezeigt werden. Erkannte CDI-Geräte erscheinen auch in docker info.

Ultralytics-Docker-Images installieren#

Ultralytics veröffentlicht die folgenden Images auf Docker Hub. Jedes Image wird anhand des verlinkten Dockerfiles durch den Docker-Veröffentlichungsworkflow erstellt.

Die AMD64-GPU-Images (latest, latest-export und latest-runner) verwenden PyTorch 2.14 und CUDA 13.2. Prüfe vor dem Start mit nvidia-smi, ob der CUDA-Treiber des Hostsystems kompatibel ist. Die Installation eines neueren Containers aktualisiert nicht den Treiber des Hostsystems. CUDA 13 stellt die Unterstützung für Maxwell-, Pascal- und Volta-GPUs ein, darunter Tesla P100 und V100. Siehe NVIDIA-CUDA-Versionshinweise und Anforderungen an die Treiberkompatibilität.

Das NVIDIA-ARM64-Image verwendet NVIDIA PyTorch 26.08 mit CUDA 13.4 und TensorRT 11.2. Die PyTorch-Unterstützung für Thor gilt nicht für TensorRT: NVIDIA unterstützt TensorRT 11.2 nicht auf JetPack. Verwende für TensorRT-Exporte auf Jetson die unterstützte TensorRT-10.x-Laufzeitumgebung für deine JetPack-Version. Befolge die Plattformanforderungen in der Jetson-Anleitung oder der DGX-Spark-Anleitung. Die Images für JetPack 4, 5 und 6 behalten ihre jeweils eigenen, gerätespezifischen Softwarepakete.

Das Conda-Dockerfile steht für lokale Builds zur Verfügung. Die automatisierte Veröffentlichung von latest-conda ist deaktiviert, daher enthält dieser Registry-Tag diese Aktualisierungen nicht.

Verwende latest-python-export für LiteRT-Exporte. Das GPU-Image latest-export behält PyTorch 2.14 bei und enthält kein LiteRT, da die aktuelle Abhängigkeit eine PyTorch-Version unter 2.14 erfordert.

Die Python-, CPU-, Jupyter- und CPU-Runner-Images verwenden Python 3.14. Das Python-Export-Image verwendet das Basis-Image latest-python-3.13, das aus demselben Dockerfile-python mit --build-arg PYTHON_VERSION=3.13 erstellt wurde, da TensorFlow, CoreML und PaddlePaddle Python 3.14 noch nicht unterstützen.

Tags mit dem Präfix latest beziehen sich auf den zuletzt veröffentlichten Build des Hauptbranches. Bei Versionstags wird das Präfix latest durch eine Ultralytics-Version ersetzt, zum Beispiel durch VERSION, VERSION-cpu oder VERSION-jetson-jetpack6. Verwende einen Versionstag für eine reproduzierbare Umgebung.

So lädst du das neueste Image herunter:

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

Wenn du stattdessen selbst ein Image erstellen möchtest, klone das Repository und übergib das passende Dockerfile aus der obigen Tabelle. Verwende dabei das Repository-Stammverzeichnis als Build-Kontext:

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Ultralytics in einem Docker-Container ausführen#

So führst du den Ultralytics-Docker-Container aus:

Nur die CPU verwenden#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

GPUs verwenden#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

Das Flag -it weist ein Pseudo-TTY zu und hält die Standardeingabe geöffnet, sodass du mit dem Container interagieren kannst. Das Flag --ipc=host ermöglicht die gemeinsame Nutzung des IPC-Namensraums des Hosts, was für den Austausch von Speicher zwischen Prozessen erforderlich ist. Für NVIDIA-GPUs gewährt das Flag --device nvidia.com/gpu=... über CDI Zugriff. Für AMD-GPUs gewähren die Flags --device Zugriff auf den GPU-Kerneltreiber (/dev/kfd) und die Renderknoten für die Anzeige (/dev/dri).

Hinweis zum Zugriff auf Dateien#

Um im Container auf Dateien deines lokalen Rechners zuzugreifen, kannst du Docker-Volumes verwenden:

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Ersetze /path/on/host durch den Verzeichnispfad auf deinem lokalen Rechner und /path/in/container durch den gewünschten Pfad im Docker-Container.

Trainingsergebnisse dauerhaft speichern#

Trainingsergebnisse werden standardmäßig im Container unter /ultralytics/runs/<task>/<name>/ gespeichert. Ohne ein eingebundenes Hostverzeichnis gehen die Ergebnisse verloren, wenn der Container entfernt wird.

So speicherst du Trainingsergebnisse dauerhaft:

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

Dadurch werden alle Trainingsergebnisse unter ./runs auf deinem Host-Rechner gespeichert.

Grafische Benutzeroberflächen (GUI) in einem Docker-Container ausführen#

Docker wird hauptsächlich verwendet, um Hintergrundanwendungen und CLI-Programme in Containern auszuführen, kann aber auch grafische Programme ausführen. In der Linux-Welt übernehmen zwei wichtige Grafikserver die grafische Anzeige: X11 (auch als X Window System bekannt) und Wayland. Bevor du loslegst, musst du unbedingt herausfinden, welchen Grafikserver du derzeit verwendest. Führe dazu diesen Befehl aus:

env | grep -E -i 'x11|xorg|wayland'

Die Einrichtung und Konfiguration eines X11- oder Wayland-Anzeigeservers ist nicht Gegenstand dieser Anleitung. Wenn der obige Befehl keine Ausgabe liefert, musst du zunächst einen der beiden Server auf deinem System zum Laufen bringen, bevor du fortfährst.

Einen Docker-Container mit grafischer Oberfläche ausführen#

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

Docker mit grafischer Oberfläche verwenden#

Ultralytics-Images werden mit einer headless-Version von OpenCV ausgeliefert. Installiere daher zuerst die Version mit grafischer Benutzeroberfläche von OpenCV und die zugehörigen Systembibliotheken im Container:

apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-python

Jetzt kannst du grafische Anwendungen in deinem Docker-Container anzeigen. Zum Beispiel kannst du den folgenden CLI-Befehl ausführen, um die Vorhersagen eines YOLO26-Modells zu visualisieren:

yolo predict model=yolo26n.pt show=True

Wenn du mit der Docker-GUI fertig bist#

xhost -local:docker

Du kannst Ultralytics jetzt mit Docker verwenden und die Funktionen nutzen. Informationen zum selbst gehosteten Betrieb der Ultralytics-Webanwendung findest du in der Anleitung zur lokalen Bereitstellung der Plattform. Alternative Installationsmethoden für Python-Pakete findest du in der Ultralytics-Schnellstartdokumentation.

Häufig gestellte Fragen#