Docker-Schnellstartanleitung für Ultralytics#
Dieser Leitfaden dient als umfassende Einführung in die Einrichtung einer Docker-Umgebung für deine Ultralytics-Projekte. Docker ist eine Plattform zum Entwickeln, Ausliefern und Ausführen von Anwendungen in Containern. Dies ist besonders vorteilhaft, um sicherzustellen, dass die Software unabhängig vom Einsatzort immer gleich läuft. Weitere Details findest du im Ultralytics Docker-Repository auf Docker Hub.
Was du lernen wirst#
- Docker mit NVIDIA-Unterstützung einrichten
- Ultralytics Docker-Images installieren
- Ultralytics in einem Docker-Container mit CPU- oder GPU-Unterstützung ausführen
- Verwendung eines Display-Servers mit Docker zur Anzeige von Ultralytics-Erkennungsergebnissen
- 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.
- Stelle für die GPU-Beschleunigung sicher, dass dein System über eine NVIDIA GPU und installierte NVIDIA-Treiber verfügt. CPU-Images erfordern keine NVIDIA-Hardware.
- Wenn du NVIDIA Jetson-Geräte verwendest, stelle sicher, dass die entsprechende JetPack-Version installiert ist. Weitere Details findest du im NVIDIA Jetson-Leitfaden.
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 die 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-toolkitÜberprüfe CDI-Geräte mit Docker#
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 generiert und pflegt 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 erscheinen auch in docker info.
Ultralytics Docker-Images installieren#
Ultralytics veröffentlicht die folgenden Images auf Docker Hub. Jedes Image wird vom verlinkten Dockerfile über 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 Export-Abhängigkeiten für Konvertierung und Benchmarking | Dockerfile-export |
latest-python | Leichtgewichtiges Linux AMD64 Python-Image für CPU-Inferenz | Dockerfile-python |
latest-python-export | Linux AMD64 CPU-Image mit Export-Abhä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-Tutorial-Notebooks | Dockerfile-jupyter |
latest-arm64 | Linux ARM64 CPU-Image für Apple Silicon, Raspberry Pi und andere ARM64-Systeme | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 mit NVIDIA GPU-Unterstützung für Jetson AGX Thor, DGX Spark, JetPack 7 und DGX OS | 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 selbstgehosteten GitHub Actions GPU-Runner | Dockerfile-runner |
latest-runner-cpu | Linux AMD64-Image für einen selbstgehosteten GitHub Actions CPU-Runner | Dockerfile-runner-cpu |
Tags, die mit latest beginnen, verfolgen den zuletzt veröffentlichten Main-Branch-Build. Versionierte Tags ersetzen das Präfix latest durch ein Ultralytics-Release, wie etwa VERSION, VERSION-cpu oder VERSION-jetson-jetpack6. Verwende ein versioniertes Tag für eine reproduzierbare Umgebung.
Um das neueste Image zu pullen:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestUm stattdessen ein Image selbst zu bauen, klone das Repository und übergebe das passende Dockerfile aus der obigen Tabelle unter Verwendung des Repository-Roots als Build-Kontext:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Ausführen von Ultralytics in einem Docker-Container#
So führst du den Ultralytics Docker-Container aus:
Nur mit CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuMit GPUs#
# 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 offen, sodass du mit dem Container interagieren kannst. Das Flag --ipc=host ermöglicht die gemeinsame Nutzung des IPC-Namensraums des Hosts, was für die gemeinsame Nutzung von Speicher zwischen Prozessen unerlässlich 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 standardmäßig aktiviert) und nvidia-container-toolkit >= 1.18 (automatische CDI-Spezifikationsgenerierung). Führe vor dem Ausführen von GPU-Containern ein Upgrade älterer Linux-Hosts durch. Das Legacy-Flag --gpus all kann den GPU-Zugriff verlieren (Failed to initialize NVML: Unknown Error), wenn der Host systemd während routinemäßiger Paket-Updates neu lädt (nvidia-container-toolkit#48). CDI---device-Anforderungen schließen die Geräteknoten in die Containerkonfiguration ein, sodass lange laufende Container wie Trainings-Worker oder CI-Runner den GPU-Zugriff über Neustarts hinweg 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 gilt der obige Daemon-Reload-Fehler nicht.
Hinweis zur Dateizugänglichkeit#
Um mit Dateien auf deinem lokalen Computer innerhalb des Containers 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 Computer und /path/in/container durch den gewünschten Pfad im Docker-Container.
Trainingsergebnisse persistent speichern#
Trainingsausgaben werden standardmäßig in /ultralytics/runs/<task>/<name>/ im Container gespeichert. Ohne das Einbinden eines Host-Verzeichnisses gehen Ausgaben verloren, wenn der Container entfernt wird.
So speicherst du Trainingsergebnisse persistent:
# 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 Trainingsausgaben in ./runs auf deinem Host-Computer gespeichert.
Grafische Benutzeroberflächen (GUI) in einem Docker-Container ausführen#
Die folgenden Anweisungen sind experimentell. Das Teilen eines X11-Sockets mit einem Docker-Container birgt potenzielle Sicherheitsrisiken. Daher wird empfohlen, diese Lösung nur in einer kontrollierten Umgebung zu testen. Weitere Informationen findest du in diesen Ressourcen zur Verwendung von xhost(1)(2).
Docker wird in erster Linie verwendet, um Hintergrundanwendungen und CLI-Programme zu containerisieren, kann aber auch grafische Programme ausführen. In der Linux-Welt verwalten zwei Hauptgrafikserver die grafische Anzeige: X11 (auch bekannt als X Window System) und Wayland. Vor dem Start ist es wichtig herauszufinden, welchen Grafikserver du aktuell verwendest. Führe diesen Befehl aus, um es herauszufinden:
env | grep -E -i 'x11|xorg|wayland'Die Einrichtung und Konfiguration eines X11- oder Wayland-Display-Servers liegt außerhalb des Geltungsbereichs dieses Leitfadens. Wenn der obige Befehl nichts zurückgibt, musst du zuerst sicherstellen, dass einer der beiden für dein System funktioniert, bevor du fortfährst.
Einen Docker-Container mit einer 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, um dem Docker-Container den Zugriff auf den X11-Socket zu ermöglichen:
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 das Display 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 einer 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
Ein einfacher Weg 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-Display-Servers zu testen. Wenn du auf Probleme stößt, ziehe in Betracht, die Umgebungsvariable -e QT_DEBUG_PLUGINS=1 zu setzen. Das Setzen dieser Umgebungsvariablen aktiviert die Ausgabe von Debugging-Informationen und unterstützt dich beim Fehlerbehebungsprozess.
Wenn du mit Docker-GUI fertig bist#
Vergiss in beiden Fällen nicht, den Zugriff der Docker-Gruppe zu widerrufen, wenn du fertig bist.
xhost -local:dockerMöchtest du Bild-Ergebnisse direkt im Terminal anzeigen?
Lies den folgenden Leitfaden zum Anzeigen der Bildergebnisse über ein Terminal
Du bist nun so weit eingerichtet, dass du Ultralytics mit Docker nutzen und von dessen Funktionen profitieren kannst. Informationen zum Selbsthosting der Ultralytics-Webanwendung findest du im Leitfaden für Plattform-On-Premises. Alternative Methoden zur Installation von Python-Paketen findest du in der Ultralytics-Schnellstart-Dokumentation.
FAQ#
Um Ultralytics mit Docker einzurichten, stelle zunächst sicher, dass Docker auf deinem System installiert ist. Wenn du eine NVIDIA GPU hast, installiere das NVIDIA Container Toolkit, um die GPU-Unterstützung zu aktivieren. Ziehe dann das neueste Ultralytics Docker-Image mit dem folgenden Befehl von Docker Hub:
sudo docker pull ultralytics/ultralytics:latestDetaillierte Schritte findest du in unserer Docker-Schnellstartanleitung.
Die Verwendung von Ultralytics Docker-Images gewährleistet eine konsistente Umgebung über verschiedene Maschinen hinweg, die dieselbe Software und Abhängigkeiten repliziert. Dies ist besonders nützlich für die Zusammenarbeit in Teams, das Ausführen von Modellen auf verschiedenen Hardwarekomponenten und die Aufrechterhaltung der Reproduzierbarkeit. Verwende
latestfür das allgemeine NVIDIA GPU-Training oder wähle das Image, das deiner JetPack-Version für ein NVIDIA Jetson-Gerät entspricht. Siehe die vollständige Image-Tabelle oder erkunde den Ultralytics Docker Hub.Stelle zunächst sicher, dass das NVIDIA Container Toolkit installiert und konfiguriert ist. Verwende dann 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 Einzelheiten 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 Display-Server gestatten. 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, die Wayland ausführen, verwende:
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 Ausführen von grafischen Benutzeroberflächen-Anwendungen (GUI) in einem Docker-Container.
Ja, du kannst lokale Verzeichnisse mit dem Flag
-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 Computer und/path/in/containerdurch den gewünschten Pfad im Container. Diese Einrichtung ermöglicht es dir, mit deinen lokalen Dateien im Container zu arbeiten. Weitere Informationen findest du im Abschnitt Hinweis zur Dateizugänglichkeit.