Guida rapida a Docker per Ultralytics#
Questa guida offre un'introduzione completa alla configurazione di un ambiente Docker per i tuoi progetti Ultralytics. Docker è una piattaforma per sviluppare, distribuire ed eseguire applicazioni in container. È particolarmente utile per garantire che il software venga sempre eseguito nello stesso modo, indipendentemente dall'ambiente in cui viene distribuito. Per ulteriori dettagli, visita il repository Docker di Ultralytics su Docker Hub.
Cosa imparerai#
- Configurare Docker con il supporto NVIDIA
- Installare le immagini Docker di Ultralytics
- Eseguire Ultralytics in un container Docker con il supporto CPU o GPU
- Usare un server di visualizzazione con Docker per mostrare i risultati del rilevamento di Ultralytics
- Montare directory locali nel container
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo 🎉
Prerequisiti#
- Assicurati che Docker sia installato nel tuo sistema. In caso contrario, puoi scaricarlo e installarlo dal sito web di Docker.
- Per l'accelerazione GPU, assicurati che il tuo sistema disponga di una GPU NVIDIA e che siano installati i driver NVIDIA. Le immagini CPU non richiedono hardware NVIDIA.
- Se usi dispositivi NVIDIA Jetson, assicurati di avere installata la versione appropriata di JetPack. Per ulteriori dettagli, consulta la guida NVIDIA Jetson.
Configurare Docker con il supporto NVIDIA (facoltativo)#
Per prima cosa, verifica che i driver NVIDIA siano installati correttamente eseguendo:
nvidia-smiInstallare NVIDIA Container Toolkit#
Ora installiamo NVIDIA Container Toolkit per abilitare il supporto GPU nei container 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.listAggiorna gli elenchi dei pacchetti e installa NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitVerificare i dispositivi CDI con Docker#
Esegui nvidia-ctk cdi list per assicurarti che i dispositivi GPU CDI siano disponibili (il servizio nvidia-cdi-refresh del toolkit genera e mantiene automaticamente la specifica su toolkit >= 1.18):
nvidia-ctk cdi listDovresti visualizzare voci come nvidia.com/gpu=0 e nvidia.com/gpu=all. I dispositivi CDI rilevati compaiono anche in docker info.
Installare le immagini Docker di Ultralytics#
Ultralytics pubblica le seguenti immagini su Docker Hub. Ogni immagine viene compilata dal Dockerfile collegato tramite il workflow di pubblicazione Docker.
| Tag | Piattaforma e scopo | Origine |
|---|---|---|
latest | Linux AMD64 con CUDA per l'addestramento e l'inferenza GPU | Dockerfile |
latest-export | Linux AMD64 con CUDA e dipendenze per l'esportazione, per la conversione e il benchmarking | Dockerfile-export |
latest-python | Immagine Python Linux AMD64 leggera per l'inferenza CPU | Dockerfile-python |
latest-python-export | Immagine Linux AMD64 CPU con dipendenze per l'esportazione | Dockerfile-python-export |
latest-cpu | Immagine Linux AMD64 CPU con Bash come comando predefinito | Dockerfile-cpu |
latest-jupyter | Immagine Linux AMD64 CPU con JupyterLab e notebook dei tutorial Ultralytics | Dockerfile-jupyter |
latest-arm64 | Immagine Linux ARM64 CPU per Apple silicon, Raspberry Pi e altri sistemi ARM64 | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 per DGX Spark (DGX OS) e PyTorch su Thor (JetPack 7.1); il TensorRT incluso non supporta JetPack | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 per dispositivi NVIDIA Jetson con JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Immagine Linux AMD64 CUDA per un runner GPU GitHub Actions self-hosted | Dockerfile-runner |
latest-runner-cpu | Immagine Linux AMD64 per un runner CPU GitHub Actions self-hosted | Dockerfile-runner-cpu |
Le immagini GPU AMD64 (latest, latest-export e latest-runner) utilizzano PyTorch 2.14 e CUDA 13.2. Verifica il supporto CUDA del driver host con nvidia-smi prima di avviarle; l'installazione di un contenitore più recente non aggiorna il driver host. CUDA 13 rimuove il supporto per le GPU Maxwell, Pascal e Volta, incluse Tesla P100 e V100. Consulta le note di rilascio CUDA di NVIDIA e i requisiti di compatibilità dei driver.
L'immagine NVIDIA ARM64 utilizza NVIDIA PyTorch 26.08 con CUDA 13.4 e TensorRT 11.2. Il supporto di PyTorch per Thor non si estende a TensorRT: NVIDIA non supporta TensorRT 11.2 su JetPack. Per le esportazioni di TensorRT su Jetson, utilizza il runtime TensorRT 10.x supportato per la tua versione di JetPack. Segui i requisiti della piattaforma nella guida Jetson o nella guida DGX Spark. Le immagini per JetPack 4, 5 e 6 mantengono i loro stack specifici per dispositivo separati.
Il Dockerfile Conda è disponibile per compilazioni locali; la pubblicazione automatica di latest-conda è disabilitata, quindi quel tag del registro non contiene questi aggiornamenti.
Usa latest-python-export per le esportazioni LiteRT. L'immagine GPU latest-export mantiene PyTorch 2.14 e omette LiteRT perché la sua dipendenza attuale richiede PyTorch inferiore a 2.14.
I tag che iniziano con latest seguono la build più recente pubblicata dal ramo principale. Nei tag con versione, il prefisso latest viene sostituito da una release Ultralytics, come VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Usa un tag con versione per un ambiente riproducibile.
Per scaricare l'immagine più recente:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestPer creare invece un'immagine autonomamente, clona il repository e passa il Dockerfile corrispondente dalla tabella precedente, usando la radice del repository come contesto di build:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Eseguire Ultralytics in un container Docker#
Ecco come eseguire il container Docker di Ultralytics:
Usare solo la CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuUsare le 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:latestIl flag -it assegna uno pseudo-TTY e mantiene stdin aperto, consentendoti di interagire con il container. Il flag --ipc=host abilita la condivisione dello spazio dei nomi IPC dell'host, essenziale per condividere la memoria tra i processi. Il flag --device nvidia.com/gpu=... consente al container di accedere alle GPU dell'host tramite CDI.
Su Linux, le richieste di dispositivi CDI richiedono Docker >= 28.2.0 (CDI è abilitato per impostazione predefinita) e nvidia-container-toolkit >= 1.18 (generazione automatica della specifica CDI). Aggiorna gli host Linux meno recenti prima di eseguire container GPU. Il flag legacy --gpus all può causare la perdita dell'accesso alla GPU (Failed to initialize NVML: Unknown Error) quando l'host ricarica systemd durante i normali aggiornamenti dei pacchetti (nvidia-container-toolkit#48). Le richieste CDI --device includono i nodi dei dispositivi nella configurazione del container, quindi i container a esecuzione prolungata, come i worker di addestramento o i runner CI, mantengono l'accesso alla GPU durante i ricaricamenti.
Il supporto GPU di Docker Desktop su Windows usa attualmente --gpus all con il backend WSL 2, poiché i dispositivi CDI NVIDIA non sono disponibili in questo ambiente. Windows non usa systemd Linux, quindi il problema di ricaricamento del demone descritto sopra non si applica.
Nota sull'accessibilità dei file#
Per lavorare con i file del tuo computer locale all'interno del container, puoi usare i volumi 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:latestSostituisci /path/on/host con il percorso della directory sul tuo computer locale e /path/in/container con il percorso desiderato all'interno del container Docker.
Salvare i risultati dell'addestramento#
Per impostazione predefinita, i risultati dell'addestramento vengono salvati in /ultralytics/runs/<task>/<name>/ all'interno del container. Se non monti una directory dell'host, i risultati vanno persi quando il container viene rimosso.
Per mantenere i risultati dell'addestramento:
# 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/runsIn questo modo tutti i risultati dell'addestramento vengono salvati in ./runs sul computer host.
Eseguire applicazioni con interfaccia grafica (GUI) in un container Docker#
Le istruzioni seguenti sono sperimentali. La condivisione di un socket X11 con un container Docker comporta potenziali rischi per la sicurezza. Pertanto, ti consigliamo di testare questa soluzione solo in un ambiente controllato. Per ulteriori informazioni, consulta queste risorse su come usare xhost(1)(2).
Docker viene usato principalmente per containerizzare applicazioni in background e programmi CLI, ma può eseguire anche programmi con interfaccia grafica. Nell'ambiente Linux, due server grafici principali gestiscono la visualizzazione: X11 (noto anche come X Window System) e Wayland. Prima di iniziare, è essenziale determinare quale server grafico stai usando attualmente. Esegui questo comando per scoprirlo:
env | grep -E -i 'x11|xorg|wayland'La configurazione di un server di visualizzazione X11 o Wayland esula dall'ambito di questa guida. Se il comando precedente non restituisce nulla, dovrai prima configurare uno dei due server sul tuo sistema prima di continuare.
Eseguire un container Docker con un'interfaccia grafica#
Usare le GPU
Se usi le GPU, puoi aggiungere il flag --device nvidia.com/gpu=all al comando.
Se usi X11, puoi eseguire il comando seguente per consentire al container Docker di accedere al 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:latestQuesto comando imposta la variabile d'ambiente DISPLAY sul display dell'host, monta il socket X11 e mappa il file .Xauthority nel container. Il comando xhost +local:docker consente al container Docker di accedere al server X11.
Usare Docker con un'interfaccia grafica#
Ora puoi visualizzare applicazioni grafiche all'interno del container Docker. Ad esempio, puoi eseguire il seguente comando CLI per visualizzare le predizioni di un modello YOLO26:
yolo predict model=yolo26n.pt show=TrueTest
Un modo semplice per verificare che il gruppo Docker abbia accesso al server X11 consiste nell'eseguire un container con un programma GUI come xclock o xeyes. In alternativa, puoi installare questi programmi anche nel container Docker di Ultralytics per testare l'accesso al server X11 del tuo server di visualizzazione GNU-Linux. Se riscontri problemi, valuta di impostare la variabile d'ambiente -e QT_DEBUG_PLUGINS=1. L'impostazione di questa variabile d'ambiente abilita l'output delle informazioni di debug, facilitando la risoluzione dei problemi.
Al termine dell'uso della GUI Docker#
In entrambi i casi, non dimenticare di revocare l'accesso del gruppo Docker quando hai finito.
xhost -local:dockerVuoi visualizzare i risultati delle immagini direttamente nel Terminale?
Consulta la guida seguente su come visualizzare i risultati delle immagini usando un terminale
Ora hai configurato Ultralytics con Docker e puoi sfruttarne le funzionalità. Per eseguire autonomamente l'applicazione web Ultralytics, consulta la guida Platform On-Premise. Per metodi alternativi di installazione del pacchetto Python, consulta la documentazione rapida di Ultralytics.
FAQ#
Per configurare Ultralytics con Docker, assicurati innanzitutto che Docker sia installato nel tuo sistema. Se disponi di una GPU NVIDIA, installa NVIDIA Container Toolkit per abilitare il supporto GPU. Quindi, scarica l'immagine Docker più recente di Ultralytics da Docker Hub usando il comando seguente:
sudo docker pull ultralytics/ultralytics:latestPer i passaggi dettagliati, consulta la nostra Guida rapida a Docker.
L'uso delle immagini Docker di Ultralytics garantisce un ambiente coerente tra macchine diverse, replicando lo stesso software e le stesse dipendenze. È particolarmente utile per collaborare tra team, eseguire modelli su hardware diversi e mantenere la riproducibilità. Usa
latestper l'addestramento generale su GPU NVIDIA oppure seleziona l'immagine corrispondente alla tua versione di JetPack per un dispositivo NVIDIA Jetson. Consulta la tabella completa delle immagini oppure esplora Ultralytics Docker Hub.Per prima cosa, assicurati che NVIDIA Container Toolkit sia installato e configurato. Quindi, usa il comando seguente per eseguire Ultralytics YOLO con il supporto GPU:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsQuesto comando configura un container Docker con accesso alla GPU. Per ulteriori dettagli, consulta la Guida rapida a Docker.
Per visualizzare i risultati delle predizioni YOLO con una GUI in un container Docker, devi consentire a Docker di accedere al tuo server di visualizzazione. Per i sistemi che eseguono X11, il comando è:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestPer i sistemi che eseguono Wayland, usa:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestUlteriori informazioni sono disponibili nella sezione Eseguire applicazioni con interfaccia grafica (GUI) in un container Docker.
Sì, puoi montare directory locali nel container Docker di Ultralytics usando il flag
-v:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestSostituisci
/path/on/hostcon la directory sul tuo computer locale e/path/in/containercon il percorso desiderato all'interno del container. Questa configurazione ti consente di lavorare con i file locali nel container. Per ulteriori informazioni, consulta la sezione Nota sull'accessibilità dei file.