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. Das 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
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Voraussetzungen#
- Stelle sicher, dass Docker auf deinem System installiert ist. Falls nicht, kannst du es von der Docker-Website herunterladen und installieren.
- Für GPU-Beschleunigung muss dein System über eine NVIDIA-GPU verfügen und NVIDIA-Treiber müssen installiert sein. CPU-Images benötigen keine NVIDIA-Hardware.
- 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)#
Überprüfe zunächst, ob die NVIDIA-Treiber ordnungsgemäß installiert sind, indem du Folgendes ausführst:
nvidia-smiNVIDIA Container Toolkit installieren#
Installiere 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.listAktualisiere die Paketlisten und installiere das NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitCDI-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 nvidia-cdi-refresh-Dienst des Toolkits erzeugt und verwaltet die Spezifikation ab Toolkit >= 1.18 automatisch):
nvidia-ctk cdi listDu solltest Einträge wie nvidia.com/gpu=0 und nvidia.com/gpu=all sehen. Erkannte CDI-Geräte werden auch in docker info angezeigt.
Ultralytics-Docker-Images installieren#
Ultralytics veröffentlicht die folgenden Images auf Docker Hub. Jedes Image wird aus der verknüpften Dockerfile durch den Docker-Veröffentlichungsworkflow erstellt.
| Tag | Plattform und Zweck | Quelle |
|---|---|---|
latest | Linux AMD64 mit CUDA für GPU-Training und -Inferenz | Dockerfile |
latest-export | Linux AMD64 mit CUDA und Exportabhängigkeiten für Konvertierung und Benchmarking | Dockerfile-export |
latest-python | Schlankes Linux-AMD64-Python-Image für CPU-Inferenz | Dockerfile-python |
latest-python-export | Linux-AMD64-CPU-Image mit Exportabhängigkeiten | Dockerfile-python-export |
latest-cpu | Linux-AMD64-CPU-Image mit Bash als Standardbefehl | Dockerfile-cpu |
latest-jupyter | Linux-AMD64-CPU-Image mit JupyterLab und Ultralytics-Tutorialnotebooks | Dockerfile-jupyter |
latest-arm64 | Linux ARM64 für Apple-Chips, Raspberry Pi und andere ARM64-Systeme | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 für DGX Spark (DGX OS) und PyTorch auf Thor (JetPack 7.1); das gebündelte TensorRT unterstützt JetPack nicht | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 für NVIDIA-Jetson-Geräte mit JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 für NVIDIA-Jetson-Geräte mit JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 für NVIDIA-Jetson-Geräte mit JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Linux-AMD64-CUDA-Image für einen selbst gehosteten GitHub-Actions-GPU-Runner | Dockerfile-runner |
latest-runner-cpu | Linux-AMD64-Image für einen selbst gehosteten GitHub-Actions-CPU-Runner | Dockerfile-runner-cpu |
Die AMD64 GPU-Images (latest, latest-export und latest-runner) verwenden PyTorch 2.14 und CUDA 13.2. Prüfe die CUDA-Unterstützung des Host-Treibers mit nvidia-smi, bevor du die AMD64 GPU-Images startest; die Installation eines neueren Containers aktualisiert den Host-Treiber nicht. CUDA 13 entfernt die Unterstützung für Maxwell-, Pascal- und Volta-GPUs, einschließlich Tesla P100 und V100. Siehe die CUDA-Release-Notes von NVIDIA und die Treiberkompatibilitätsanforderungen.
Das NVIDIA ARM64-Image verwendet NVIDIA PyTorch 26.08 mit CUDA 13.4 und TensorRT 11.2. Dessen PyTorch-Unterstützung für Thor erstreckt sich nicht auf TensorRT: NVIDIA unterstützt TensorRT 11.2 unter JetPack nicht. Verwende für Jetson TensorRT-Exporte die unterstützte TensorRT 10.x-Laufzeitumgebung für dein JetPack-Release. Beachte die Plattformanforderungen im Jetson-Leitfaden oder DGX Spark-Leitfaden. Die JetPack 4-, 5- und 6-Images behalten ihre separaten gerätespezifischen Stacks bei.
Das Conda Dockerfile ist für lokale Builds verfügbar; die automatisierte Verfügbarmachung von latest-conda ist deaktiviert, sodass dieses Registry-Tag diese Aktualisierungen nicht enthält.
Verwende latest-python-export für LiteRT-Exporte. Das GPU latest-export-Image behält PyTorch 2.14 bei und lässt LiteRT weg, da dessen aktuelle Abhängigkeit ein PyTorch unter 2.14 erfordert.
Tags, die mit latest beginnen, beziehen sich auf den zuletzt veröffentlichten Build des Hauptzweigs. Bei versionierten Tags wird das Präfix latest durch eine Ultralytics-Version wie VERSION, VERSION-cpu oder VERSION-jetson-jetpack6 ersetzt. Verwende für eine reproduzierbare Umgebung ein versioniertes Tag.
So rufst du das neueste Image ab:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestUm stattdessen selbst ein Image zu erstellen, klone das Repository und übergib die 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-cpuGPUs 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:latestDas Flag -it weist ein pseudo-TTY zu und hält stdin geöffnet, sodass du mit dem Container interagieren kannst. Das Flag --ipc=host aktiviert die gemeinsame Nutzung des IPC-Namensraums des Hosts, was für die gemeinsame Speichernutzung zwischen Prozessen erforderlich ist. Das Flag --device nvidia.com/gpu=... gewährt dem Container über CDI Zugriff auf die GPUs des Hosts.
Unter Linux erfordern CDI-Geräteanforderungen Docker >= 28.2.0 (CDI ist standardmäßig aktiviert) und nvidia-container-toolkit >= 1.18 (automatische Erzeugung der CDI-Spezifikation). Aktualisiere ältere Linux-Hosts, bevor du GPU-Container ausführst. Das veraltete Flag --gpus all kann den GPU-Zugriff (Failed to initialize NVML: Unknown Error) verlieren, wenn der Host bei routinemäßigen Paketaktualisierungen systemd neu lädt (nvidia-container-toolkit#48). CDI---device-Anforderungen enthalten die Geräteknoten in der Containerkonfiguration, sodass langlebige Container wie Trainings-Worker oder CI-Runner den GPU-Zugriff auch nach Neuladungen behalten.
Docker-Desktop-GPU-Unterstützung unter Windows verwendet derzeit --gpus all mit dem WSL-2-Backend, da NVIDIA-CDI-Geräte dort nicht verfügbar sind. Windows verwendet kein Linux-systemd, daher trifft der oben beschriebene Fehler beim Neuladen des Daemons nicht zu.
Hinweis zur Dateizugänglichkeit#
Um im Container mit Dateien auf deinem lokalen Rechner zu arbeiten, 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:latestErsetze /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 das Einbinden eines Hostverzeichnisses 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/runsDadurch werden alle Trainingsergebnisse unter ./runs auf deinem Hostcomputer gespeichert.
Anwendungen mit grafischer Benutzeroberfläche (GUI) in einem Docker-Container ausführen#
Die folgenden Anweisungen sind experimentell. Die Freigabe eines X11-Sockets für einen Docker-Container birgt potenzielle Sicherheitsrisiken. Daher wird empfohlen, diese Lösung nur in einer kontrollierten Umgebung zu testen. Weitere Informationen zur Verwendung von xhost findest du in diesen Ressourcen(1)(2).
Docker wird hauptsächlich verwendet, um Hintergrundanwendungen und CLI-Programme zu containerisieren, kann aber auch grafische Programme ausführen. In der Linux-Welt übernehmen zwei wichtige Grafikserver die grafische Darstellung: X11 (auch als X Window System bekannt) und Wayland. Vor dem Start musst du unbedingt feststellen, welchen Grafikserver du derzeit verwendest. Führe diesen Befehl aus:
env | grep -E -i 'x11|xorg|wayland'Die Einrichtung und Konfiguration eines X11- oder Wayland-Anzeigeservers ist nicht Bestandteil dieser Anleitung. Wenn der obige Befehl keine Ausgabe liefert, musst du zunächst einen der beiden Server auf deinem System funktionsfähig einrichten, bevor du fortfährst.
Docker-Container mit GUI ausführen#
GPUs verwenden
Wenn du GPUs verwendest, kannst du das Flag --device nvidia.com/gpu=all zum Befehl hinzufügen.
Wenn du X11 verwendest, kannst du den folgenden Befehl ausführen, damit der Docker-Container auf den X11-Socket zugreifen kann:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latestDieser Befehl setzt die Umgebungsvariable DISPLAY auf die Anzeige des Hosts, bindet den X11-Socket ein und ordnet die Datei .Xauthority dem Container zu. Der Befehl xhost +local:docker ermöglicht dem Docker-Container den Zugriff auf den X11-Server.
Docker mit GUI verwenden#
Jetzt kannst du grafische Anwendungen in deinem Docker-Container anzeigen. Du kannst beispielsweise den folgenden CLI-Befehl ausführen, um die Vorhersagen eines YOLO26-Modells zu visualisieren:
yolo predict model=yolo26n.pt show=TrueTesten
Eine einfache Möglichkeit zu überprüfen, ob die Docker-Gruppe Zugriff auf den X11-Server hat, besteht darin, einen Container mit einem GUI-Programm wie xclock oder xeyes auszuführen. Alternativ kannst du diese Programme auch im Ultralytics-Docker-Container installieren, um den Zugriff auf den X11-Server deines GNU-Linux-Anzeigeservers zu testen. Falls Probleme auftreten, kannst du die Umgebungsvariable -e QT_DEBUG_PLUGINS=1 setzen. Dadurch wird die Ausgabe von Debugging-Informationen aktiviert, was die Fehlersuche erleichtert.
Nach der Verwendung der Docker-GUI#
Vergiss in beiden Fällen nicht, den Zugriff der Docker-Gruppe zu widerrufen, wenn du fertig bist.
xhost -local:dockerMöchtest du Bildergebnisse direkt im Terminal anzeigen?
Weitere Informationen findest du in der folgenden Anleitung zum Anzeigen von Bildergebnissen mit einem Terminal.
Du kannst Ultralytics jetzt mit Docker verwenden und seine Funktionen nutzen. Informationen zum Selbsthosten der Ultralytics-Webanwendung findest du in der Anleitung zur On-Premise-Plattform. Alternative Installationsmethoden für das Python-Paket findest du in der Ultralytics-Schnellstartdokumentation.
FAQ#
Stelle zunächst sicher, dass Docker auf deinem System installiert ist. Wenn du über eine NVIDIA-GPU verfügst, installiere das NVIDIA Container Toolkit, um GPU-Unterstützung zu aktivieren. Rufe anschließend das neueste Ultralytics-Docker-Image mit dem folgenden Befehl von Docker Hub ab:
sudo docker pull ultralytics/ultralytics:latestEine ausführliche Anleitung findest du in unserer Docker-Schnellstartanleitung.
Die Verwendung von Ultralytics-Docker-Images stellt eine konsistente Umgebung auf verschiedenen Rechnern sicher, da dieselbe Software und dieselben Abhängigkeiten verwendet werden. Das ist besonders nützlich für die Zusammenarbeit zwischen Teams, die Ausführung von Modellen auf verschiedener Hardware und die Wahrung der Reproduzierbarkeit. Verwende
latestfür allgemeines NVIDIA-GPU-Training oder wähle für ein NVIDIA-Jetson-Gerät das Image aus, das zu deiner JetPack-Version passt. Sieh dir die vollständige Image-Tabelle an oder erkunde Ultralytics Docker Hub.Stelle zunächst sicher, dass das NVIDIA Container Toolkit installiert und konfiguriert ist. Verwende anschließend den folgenden Befehl, um Ultralytics YOLO mit GPU-Unterstützung auszuführen:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsDieser Befehl richtet einen Docker-Container mit GPU-Zugriff ein. Weitere Informationen findest du in der Docker-Schnellstartanleitung.
Um YOLO-Vorhersageergebnisse mit einer GUI in einem Docker-Container zu visualisieren, musst du Docker den Zugriff auf deinen Anzeigeserver erlauben. Für Systeme mit X11 lautet der Befehl:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestFür Systeme mit Wayland verwendest du:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestWeitere Informationen findest du im Abschnitt Anwendungen mit grafischer Benutzeroberfläche (GUI) in einem Docker-Container ausführen.
Ja, du kannst lokale Verzeichnisse mithilfe des Flags
-vin den Ultralytics-Docker-Container einbinden:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestErsetze
/path/on/hostdurch das Verzeichnis auf deinem lokalen Rechner und/path/in/containerdurch den gewünschten Pfad im Container. Dadurch kannst du im Container mit deinen lokalen Dateien arbeiten. Weitere Informationen findest du im Abschnitt Hinweis zur Dateizugänglichkeit.