Guide de démarrage rapide Docker pour Ultralytics#

Ce guide est une introduction complète à la configuration d’un environnement Docker pour tes projets Ultralytics. Docker est une plateforme permettant de développer, distribuer et exécuter des applications dans des conteneurs. Elle est particulièrement utile pour garantir que le logiciel s’exécute toujours de la même manière, quel que soit son environnement de déploiement. Pour en savoir plus, consulte le dépôt Docker Ultralytics sur Docker Hub.

Ce que tu vas apprendre#

• Configurer Docker avec la prise en charge de NVIDIA
• Installer les images Docker Ultralytics
• Exécuter Ultralytics dans un conteneur Docker avec prise en charge du CPU ou du GPU
• Utiliser un serveur d’affichage avec Docker pour afficher les résultats de détection Ultralytics
• Monter des répertoires locaux dans le conteneur

Prérequis#

• Assure-toi que Docker est installé sur ton système. Sinon, tu peux le télécharger et l’installer depuis le site Web de Docker.
• Pour accélérer le calcul avec le GPU, vérifie que ton système est équipé 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, vérifie que la version appropriée de JetPack est installée. Consulte le guide NVIDIA Jetson pour en savoir plus.

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 :

nvidia-smi

Installer NVIDIA Container Toolkit#

Installons maintenant 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.list

sudo apt-get update

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

Vérifier les appareils CDI avec Docker#

Exécute nvidia-ctk cdi list pour vérifier que les appareils GPU CDI sont disponibles (le service nvidia-cdi-refresh de la boîte à outils génère et maintient automatiquement la spécification avec toolkit >= 1.18) :

nvidia-ctk cdi list

Tu devrais voir des entrées telles que nvidia.com/gpu=0 et nvidia.com/gpu=all. Les appareils CDI détectés apparaissent aussi dans docker info.

Installer les images Docker Ultralytics#

Ultralytics publie les images suivantes sur Docker Hub. Chaque image est construite à partir du Dockerfile associé par le workflow de publication Docker.

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 l’hôte avec nvidia-smi avant de les lancer : l’installation d’un conteneur plus récent ne met pas à niveau le pilote de l’hôte. CUDA 13 ne prend plus en charge les GPU Maxwell, Pascal et Volta, notamment 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. La prise en charge de Thor par PyTorch ne s’étend pas à TensorRT : NVIDIA ne prend pas en charge TensorRT 11.2 sur JetPack. Pour les exports TensorRT sur Jetson, utilise l’environnement d’exécution TensorRT 10.x pris en charge pour ta version de JetPack. Respecte les exigences de la plateforme indiquées dans le guide Jetson ou le guide DGX Spark. Les images JetPack 4, 5 et 6 conservent leurs piles logicielles spécifiques à chaque appareil.

Le Dockerfile Conda est disponible pour les compilations locales ; la publication automatisée de latest-conda est désactivée, cette étiquette du registre ne contient donc pas ces mises à jour.

Utilise latest-python-export pour les exports LiteRT. L’image GPU latest-export conserve PyTorch 2.14 et n’inclut pas LiteRT, car sa dépendance actuelle nécessite une version de PyTorch antérieure à 2.14.

Les images Python, CPU, Jupyter et runner CPU utilisent Python 3.14. L’image Python pour l’export utilise la base latest-python-3.13, construite à partir du même Dockerfile-python avec --build-arg PYTHON_VERSION=3.13, car TensorFlow, CoreML et PaddlePaddle ne prennent pas encore en charge Python 3.14.

Les étiquettes commençant par latest correspondent à la version la plus récemment publiée depuis la branche principale. Les étiquettes versionnées remplacent le préfixe latest par une version Ultralytics, comme VERSION, VERSION-cpu ou VERSION-jetson-jetpack6. Utilise une étiquette versionnée pour obtenir un environnement reproductible.

Pour récupérer la dernière image :

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

Pour construire toi-même une image, clone le dépôt et indique le Dockerfile correspondant dans le tableau ci-dessus, en utilisant la racine du dépôt comme contexte de compilation :

# 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 Ultralytics :

Utiliser uniquement le CPU#

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

Utiliser 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:latest

L’option -it alloue un pseudo-terminal et garde 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 au partage de mémoire entre les processus. Pour les GPU NVIDIA, l’option --device nvidia.com/gpu=... autorise l’accès via CDI. Pour les GPU AMD, les options --device autorisent l’accès au pilote du noyau GPU (/dev/kfd) et aux nœuds de rendu d’affichage (/dev/dri).

Remarque sur l’accès aux fichiers#

Pour accéder aux fichiers de 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:latest

Remplace /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 de l’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/runs

Cette 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#

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. Sous Linux, deux principaux serveurs graphiques 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 savoir :

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

La configuration d’un serveur d’affichage X11 ou Wayland n’entre pas dans le 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#

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

Utiliser Docker avec une interface graphique#

Les images Ultralytics incluent une version sans interface graphique d’OpenCV. Installe donc d’abord la version avec interface graphique d’OpenCV et ses bibliothèques système dans le conteneur :

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

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=True

Après avoir utilisé l’interface graphique de Docker#

xhost -local:docker

Tu peux maintenant utiliser Ultralytics avec Docker et profiter de ses fonctionnalités. Pour héberger toi-même l’application Web Ultralytics, consulte le guide sur la plateforme sur site. Pour découvrir d’autres méthodes d’installation du package Python, consulte la documentation de démarrage rapide d’Ultralytics.

FAQ#