Guide de démarrage rapide de Docker pour Ultralytics#
Ce guide constitue une introduction complète à la configuration d'un environnement Docker pour tes projets Ultralytics. Docker est une plateforme qui permet de développer, de distribuer et d'exécuter des applications dans des conteneurs. Il est particulièrement utile pour garantir que le logiciel fonctionne toujours de la même manière, quel que soit son environnement de déploiement. Pour plus de détails, consulte le dépôt Docker d'Ultralytics sur Docker Hub.
Ce que tu vas apprendre#
- Configurer Docker avec la prise en charge de NVIDIA
- Installer les images Docker d'Ultralytics
- Exécuter Ultralytics dans un conteneur Docker avec la prise en charge du CPU ou du GPU
- Utiliser un serveur d'affichage avec Docker pour afficher les résultats de détection d'Ultralytics
- Monter des répertoires locaux dans le conteneur
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Prérequis#
- Assure-toi que Docker est installé sur ton système. Si ce n'est pas le cas, tu peux le télécharger et l'installer depuis le site web de Docker.
- Pour l'accélération GPU, assure-toi que ton système dispose d'un GPU NVIDIA et que les pilotes NVIDIA sont installés. Les images CPU ne nécessitent pas de matériel NVIDIA.
- Si tu utilises des appareils NVIDIA Jetson, assure-toi que la version appropriée de JetPack est installée. Consulte le guide NVIDIA Jetson pour plus de détails.
Configurer Docker avec la prise en charge de NVIDIA (facultatif)#
Commence par vérifier que les pilotes NVIDIA sont correctement installés en exécutant la commande suivante :
nvidia-smiInstaller NVIDIA Container Toolkit#
Installons maintenant le NVIDIA Container Toolkit pour activer la prise en charge du GPU dans les conteneurs Docker :
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.listMets à jour les listes de paquets et installe le NVIDIA Container Toolkit :
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitVérifier les appareils CDI avec Docker#
Exécute nvidia-ctk cdi list pour t'assurer que les appareils GPU CDI sont disponibles (le service nvidia-cdi-refresh du toolkit génère et gère automatiquement la spécification avec toolkit >= 1.18) :
nvidia-ctk cdi listTu devrais voir des entrées telles que nvidia.com/gpu=0 et nvidia.com/gpu=all. Les appareils CDI détectés apparaissent également dans docker info.
Installer les images Docker d'Ultralytics#
Ultralytics publie les images suivantes sur Docker Hub. Chaque image est créée à partir du Dockerfile associé par le workflow de publication Docker.
| Tag | Plateforme et objectif | Source |
|---|---|---|
latest | Linux AMD64 avec CUDA pour l'entraînement et l'inférence sur GPU | Dockerfile |
latest-export | Linux AMD64 avec CUDA et les dépendances d'exportation pour la conversion et l'évaluation des performances | Dockerfile-export |
latest-python | Image Python Linux AMD64 légère pour l'inférence sur CPU | Dockerfile-python |
latest-python-export | Image Linux AMD64 CPU avec les dépendances d'exportation | Dockerfile-python-export |
latest-cpu | Image Linux AMD64 CPU avec Bash comme commande par défaut | Dockerfile-cpu |
latest-jupyter | Image Linux AMD64 CPU avec JupyterLab et les notebooks des tutoriels Ultralytics | Dockerfile-jupyter |
latest-arm64 | Image Linux ARM64 CPU pour les puces Apple, Raspberry Pi et les autres systèmes ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 pour DGX Spark (DGX OS) et PyTorch sur Thor (JetPack 7.1) ; le TensorRT fourni ne prend pas en charge JetPack | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 pour les appareils NVIDIA Jetson exécutant JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Image Linux AMD64 CUDA pour un runner GPU GitHub Actions autohébergé | Dockerfile-runner |
latest-runner-cpu | Image Linux AMD64 pour un runner CPU GitHub Actions autohébergé | Dockerfile-runner-cpu |
Les images GPU AMD64 (latest, latest-export et latest-runner) utilisent PyTorch 2.14 et CUDA 13.2. Vérifie la prise en charge de CUDA par le pilote de ton hôte avec nvidia-smi avant de les lancer ; l'installation d'un conteneur plus récent ne met pas à niveau le pilote de ton hôte. CUDA 13 supprime la prise en charge des GPU Maxwell, Pascal et Volta, y compris Tesla P100 et V100. Consulte les notes de version de CUDA de NVIDIA et les exigences de compatibilité des pilotes.
L'image NVIDIA ARM64 utilise NVIDIA PyTorch 26.08 avec CUDA 13.4 et TensorRT 11.2. Sa prise en charge de PyTorch pour Thor ne s'étend pas à TensorRT : NVIDIA ne prend pas en charge TensorRT 11.2 sur JetPack. Pour les exportations TensorRT sur Jetson, utilise le runtime TensorRT 10.x pris en charge pour ta version de JetPack. Respecte les exigences de la plateforme dans le guide Jetson ou le guide DGX Spark. Les images JetPack 4, 5 et 6 conservent leurs piles spécifiques aux appareils séparées.
Le fichier Dockerfile Conda est disponible pour les compilations locales ; la publication automatisée de latest-conda est désactivée, de sorte que cette balise de registre ne contient pas ces mises à jour.
Utilise latest-python-export pour les exportations LiteRT. L'image GPU latest-export conserve PyTorch 2.14 et omet LiteRT parce que sa dépendance actuelle nécessite PyTorch inférieur à 2.14.
Les tags commençant par latest correspondent à la build publiée la plus récente de la branche principale. Les tags versionnés remplacent le préfixe latest par une version Ultralytics, comme VERSION, VERSION-cpu ou VERSION-jetson-jetpack6. Utilise un tag versionné pour obtenir un environnement reproductible.
Pour télécharger la dernière image :
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestPour créer toi-même une image, clone plutôt le dépôt et indique le Dockerfile correspondant du tableau ci-dessus, en utilisant la racine du dépôt comme contexte de build :
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Exécuter Ultralytics dans un conteneur Docker#
Voici comment exécuter le conteneur Docker d'Ultralytics :
Utiliser uniquement le CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuUtiliser des GPU#
# 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:latestL'option -it attribue un pseudo-TTY et maintient stdin ouvert, ce qui te permet d'interagir avec le conteneur. L'option --ipc=host active le partage de l'espace de noms IPC de l'hôte, indispensable pour partager la mémoire entre les processus. L'option --device nvidia.com/gpu=... autorise le conteneur à accéder aux GPU de l'hôte via CDI.
Sous Linux, les demandes d'appareils CDI nécessitent Docker >= 28.2.0 (CDI est activé par défaut) et nvidia-container-toolkit >= 1.18 (génération automatique de la spécification CDI). Mets à niveau les hôtes Linux plus anciens avant d'exécuter des conteneurs GPU. L'option héritée --gpus all peut entraîner la perte de l'accès au GPU (Failed to initialize NVML: Unknown Error) lorsque l'hôte recharge systemd lors des mises à jour régulières des paquets (nvidia-container-toolkit#48). Les demandes CDI --device incluent les nœuds d'appareils dans la configuration du conteneur ; les conteneurs de longue durée, comme les workers d'entraînement ou les runners CI, conservent donc leur accès au GPU après les rechargements.
La prise en charge des GPU par Docker Desktop sous Windows utilise actuellement --gpus all avec le backend WSL 2, car les appareils CDI NVIDIA n'y sont pas disponibles. Windows n'utilise pas systemd Linux ; l'échec de daemon-reload décrit ci-dessus ne s'applique donc pas.
Remarque sur l'accessibilité des fichiers#
Pour travailler avec des fichiers présents sur ta machine locale depuis le conteneur, tu peux utiliser des volumes Docker :
# 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:latestRemplace /path/on/host par le chemin du répertoire sur ta machine locale et /path/in/container par le chemin souhaité dans le conteneur Docker.
Conserver les sorties d'entraînement#
Par défaut, les sorties d'entraînement sont enregistrées dans /ultralytics/runs/<task>/<name>/ à l'intérieur du conteneur. Si tu ne montes pas de répertoire hôte, les sorties sont perdues lorsque le conteneur est supprimé.
Pour conserver les sorties d'entraînement :
# 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/runsCette commande enregistre toutes les sorties d'entraînement dans ./runs sur ta machine hôte.
Exécuter des applications à interface graphique (GUI) dans un conteneur Docker#
Les instructions suivantes sont expérimentales. Le partage d'un socket X11 avec un conteneur Docker présente des risques potentiels pour la sécurité. Il est donc recommandé de tester cette solution uniquement dans un environnement contrôlé. Pour plus d'informations, consulte ces ressources sur l'utilisation de xhost(1)(2).
Docker est principalement utilisé pour conteneuriser des applications en arrière-plan et des programmes CLI, mais il peut également exécuter des programmes graphiques. Dans l'environnement Linux, deux serveurs graphiques principaux gèrent l'affichage : X11 (également appelé système X Window) et Wayland. Avant de commencer, il est essentiel de déterminer quel serveur graphique tu utilises actuellement. Exécute cette commande pour le vérifier :
env | grep -E -i 'x11|xorg|wayland'La configuration d'un serveur d'affichage X11 ou Wayland sort du cadre de ce guide. Si la commande ci-dessus ne renvoie rien, tu devras d'abord faire fonctionner l'un de ces serveurs sur ton système avant de continuer.
Exécuter un conteneur Docker avec une interface graphique#
Utiliser des GPU
Si tu utilises des GPU, tu peux ajouter l'option --device nvidia.com/gpu=all à la commande.
Si tu utilises X11, tu peux exécuter la commande suivante pour autoriser le conteneur Docker à accéder au socket X11 :
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latestCette commande définit la variable d'environnement DISPLAY sur l'affichage de l'hôte, monte le socket X11 et mappe le fichier .Xauthority dans le conteneur. La commande xhost +local:docker autorise le conteneur Docker à accéder au serveur X11.
Utiliser Docker avec une interface graphique#
Tu peux maintenant afficher des applications graphiques dans ton conteneur Docker. Par exemple, tu peux exécuter la commande CLI suivante pour visualiser les prédictions d'un modèle YOLO26 :
yolo predict model=yolo26n.pt show=TrueTester
Pour vérifier simplement que le groupe Docker peut accéder au serveur X11, exécute un conteneur avec un programme GUI comme xclock ou xeyes. Tu peux également installer ces programmes dans le conteneur Docker d'Ultralytics afin de tester l'accès au serveur X11 de ton serveur d'affichage GNU-Linux. Si tu rencontres des problèmes, essaie de définir la variable d'environnement -e QT_DEBUG_PLUGINS=1. La définition de cette variable d'environnement active l'affichage des informations de débogage, ce qui facilite le dépannage.
Après avoir terminé avec l'interface graphique Docker#
Dans les deux cas, n'oublie pas de révoquer l'accès du groupe Docker lorsque tu as terminé.
xhost -local:dockerTu veux afficher directement les résultats des images dans le Terminal ?
Consulte le guide suivant sur l'affichage des résultats d'images dans un terminal
Tu peux désormais utiliser Ultralytics avec Docker et profiter de ses fonctionnalités. Pour autohéberger l'application web Ultralytics, consulte le guide de la plateforme On-Premise. Pour connaître d'autres méthodes d'installation du paquet Python, consulte la documentation de démarrage rapide d'Ultralytics.
FAQ#
L'utilisation des images Docker d'Ultralytics garantit un environnement cohérent entre différentes machines, en reproduisant les mêmes logiciels et dépendances. Cela est particulièrement utile pour collaborer entre équipes, exécuter des modèles sur différents matériels et maintenir la reproductibilité. Utilise
latestpour l'entraînement général sur GPU NVIDIA ou sélectionne l'image correspondant à ta version de JetPack pour un appareil NVIDIA Jetson. Consulte le tableau complet des images ou explore Ultralytics Docker Hub.Commence par vérifier que le NVIDIA Container Toolkit est installé et configuré. Utilise ensuite la commande suivante pour exécuter Ultralytics YOLO avec la prise en charge du GPU :
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsCette commande configure un conteneur Docker avec un accès au GPU. Pour plus de détails, consulte le guide de démarrage rapide Docker.
Pour visualiser les résultats des prédictions YOLO avec une interface graphique dans un conteneur Docker, tu dois autoriser Docker à accéder à ton serveur d'affichage. Pour les systèmes exécutant X11, la commande est la suivante :
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestPour les systèmes utilisant Wayland, utilise :
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestTu trouveras plus d'informations dans la section Exécuter des applications à interface graphique (GUI) dans un conteneur Docker.
Oui, tu peux monter des répertoires locaux dans le conteneur Docker d'Ultralytics à l'aide de l'option
-v:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestRemplace
/path/on/hostpar le répertoire de ta machine locale et/path/in/containerpar le chemin souhaité dans le conteneur. Cette configuration te permet de travailler avec tes fichiers locaux depuis le conteneur. Pour plus d'informations, consulte la section Remarque sur l'accessibilité des fichiers.
Pour configurer Ultralytics avec Docker, vérifie d'abord que Docker est installé sur ton système. Si tu disposes d'un GPU NVIDIA, installe le NVIDIA Container Toolkit pour activer la prise en charge du GPU. Télécharge ensuite la dernière image Docker d'Ultralytics depuis Docker Hub à l'aide de la commande suivante :
Pour obtenir des étapes détaillées, consulte notre guide de démarrage rapide Docker.