Guida rapida a Docker per Ultralytics#

Questa guida è 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 funzioni sempre allo stesso modo, indipendentemente dall'ambiente in cui viene distribuito. Per maggiori 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 supporto CPU o GPU
• Usare un display server con Docker per visualizzare i risultati del rilevamento di Ultralytics
• Montare directory locali nel container

Prerequisiti#

• Assicurati che Docker sia installato sul tuo sistema. In caso contrario, puoi scaricarlo e installarlo dal sito web di Docker.
• Per l'accelerazione GPU, verifica che nel sistema sia installata una GPU NVIDIA e che siano installati i driver NVIDIA. Le immagini CPU non richiedono hardware NVIDIA.
• Se usi dispositivi NVIDIA Jetson, assicurati di aver installato la versione appropriata di JetPack. Per maggiori 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-smi

Installazione di 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.list

sudo apt-get update

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

Verificare i dispositivi CDI con Docker#

Esegui nvidia-ctk cdi list per verificare che i dispositivi GPU CDI siano disponibili (il servizio nvidia-cdi-refresh del toolkit genera e mantiene automaticamente la specifica con toolkit >= 1.18):

nvidia-ctk cdi list

Dovresti vedere voci come nvidia.com/gpu=0 e nvidia.com/gpu=all. I dispositivi CDI rilevati compaiono anche in docker info.

Installazione delle immagini Docker di Ultralytics#

Ultralytics pubblica le seguenti immagini su Docker Hub. Ogni immagine viene compilata a partire dal Dockerfile collegato tramite il workflow di pubblicazione Docker.

Le immagini GPU AMD64 (latest, latest-export e latest-runner) usano PyTorch 2.14 e CUDA 13.2. Prima di avviarle, verifica il supporto CUDA del driver host con nvidia-smi; installare un container 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 di CUDA di NVIDIA e i requisiti di compatibilità dei driver.

L'immagine NVIDIA ARM64 usa 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 TensorRT su Jetson, usa 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 stack distinti specifici per dispositivo.

Il Dockerfile Conda è disponibile per le build locali; la pubblicazione automatizzata di latest-conda è disabilitata, quindi quel tag del registry non contiene questi aggiornamenti.

Usa latest-python-export per le esportazioni LiteRT. L'immagine GPU latest-export mantiene PyTorch 2.14 e non include LiteRT, perché la sua dipendenza attuale richiede una versione di PyTorch precedente alla 2.14.

Le immagini Python, CPU, Jupyter e runner CPU usano Python 3.14. L'immagine Python per l'esportazione usa la base latest-python-3.13, creata a partire dallo stesso Dockerfile-python con --build-arg PYTHON_VERSION=3.13, perché TensorFlow, CoreML e PaddlePaddle non supportano ancora Python 3.14.

I tag che iniziano con latest seguono la build più recente pubblicata dal branch main. Nei tag con versione, il prefisso latest è sostituito da una release Ultralytics, ad esempio VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Usa un tag con versione per ottenere un ambiente riproducibile.

Per scaricare l'immagine più recente:

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

Per compilare invece un'immagine autonomamente, clona il repository e specifica il Dockerfile corrispondente dalla tabella precedente, usando la directory principale 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 .

Esecuzione di 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-cpu

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

Il flag -it assegna uno pseudo-TTY e mantiene aperto stdin, permettendoti 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 processi. Per le GPU NVIDIA, il flag --device nvidia.com/gpu=... concede l'accesso tramite CDI. Per le GPU AMD, i flag --device concedono l'accesso al driver del kernel GPU (/dev/kfd) e ai nodi di rendering del display (/dev/dri).

Nota sull'accessibilità dei file#

Per usare nel container i file presenti sul computer locale, puoi utilizzare 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:latest

Sostituisci /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.

Mantenere gli output dell'addestramento#

Per impostazione predefinita, gli output dell'addestramento vengono salvati in /ultralytics/runs/<task>/<name>/ all'interno del container. Se non monti una directory dell'host, gli output andranno persi quando il container verrà rimosso.

Per mantenere gli output 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/runs

In questo modo, tutti gli output dell'addestramento vengono salvati in ./runs sul computer host.

Eseguire applicazioni con interfaccia grafica (GUI) in un container Docker#

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. Esegui questo comando per scoprirlo:

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

La configurazione di un server grafico X11 o Wayland non rientra nell'ambito di questa guida. Se il comando precedente non restituisce nulla, prima di continuare dovrai assicurarti che uno dei due funzioni sul tuo sistema.

Eseguire un container Docker con un'interfaccia grafica#

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

Usare Docker con un'interfaccia grafica#

Le immagini Ultralytics includono OpenCV headless, quindi installa prima nel container la versione con GUI di OpenCV e le relative librerie di sistema:

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

Ora puoi visualizzare applicazioni grafiche all'interno del tuo container Docker. Ad esempio, puoi eseguire il seguente comando CLI per visualizzare le predizioni di un modello YOLO26:

yolo predict model=yolo26n.pt show=True

Al termine dell'uso della GUI Docker#

xhost -local:docker

Ora hai configurato Ultralytics con Docker e puoi sfruttarne le funzionalità. Per ospitare autonomamente l'applicazione web Ultralytics, consulta la guida alla piattaforma on-premise. Per metodi alternativi di installazione del pacchetto Python, consulta la documentazione introduttiva di Ultralytics.

Domande frequenti#