Link to this sectionGuía de inicio rápido de Docker para Ultralytics#

Esta guía sirve como una introducción completa para configurar un entorno Docker para tus proyectos de Ultralytics. Docker es una plataforma para desarrollar, enviar y ejecutar aplicaciones en contenedores. Es especialmente beneficiosa para garantizar que el software siempre se ejecute igual, independientemente de dónde se implemente. Para obtener más detalles, visita el repositorio de Docker de Ultralytics en Docker Hub.

Link to this sectionLo que aprenderás#

• Configuración de Docker con soporte para NVIDIA
• Instalación de imágenes de Docker de Ultralytics
• Ejecución de Ultralytics en un contenedor Docker con soporte para CPU o GPU
• Uso de un servidor de pantalla con Docker para mostrar los resultados de detección de Ultralytics
• Montaje de directorios locales en el contenedor

Link to this sectionRequisitos previos#

• Asegúrate de que Docker esté instalado en tu sistema. Si no es así, puedes descargarlo e instalarlo desde el sitio web de Docker.
• Para la aceleración por GPU, asegúrate de que tu sistema tenga una GPU NVIDIA y los NVIDIA drivers instalados. Las imágenes de CPU no requieren hardware de NVIDIA.
• Si utilizas dispositivos NVIDIA Jetson, asegúrate de tener instalada la versión adecuada de JetPack. Consulta la guía de NVIDIA Jetson para obtener más detalles.

Link to this sectionConfigurar Docker con soporte para NVIDIA (opcional)#

Primero, verifica que los controladores de NVIDIA estén instalados correctamente ejecutando:

nvidia-smi

Link to this sectionInstalación de NVIDIA Container Toolkit#

Ahora, instalemos el NVIDIA Container Toolkit para habilitar el soporte de GPU en los contenedores 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

Link to this sectionVerifica los dispositivos CDI con Docker#

Ejecuta nvidia-ctk cdi list para asegurarte de que los dispositivos CDI de la GPU están disponibles (el servicio nvidia-cdi-refresh del toolkit genera y mantiene la especificación automáticamente en versiones del toolkit >= 1.18):

nvidia-ctk cdi list

Deberías ver entradas como nvidia.com/gpu=0 y nvidia.com/gpu=all. Los dispositivos CDI detectados también aparecen en docker info.

Link to this sectionInstalación de imágenes de Docker de Ultralytics#

Ultralytics publica las siguientes imágenes en Docker Hub. Cada imagen se construye a partir de su Dockerfile vinculado mediante el Docker publishing workflow.

Las etiquetas que comienzan con latest siguen la compilación de la rama principal publicada más recientemente. Las etiquetas con versión reemplazan el prefijo latest con una versión de Ultralytics, como VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Usa una etiqueta con versión para un entorno reproducible.

Para descargar la última imagen:

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

Link to this sectionEjecución de Ultralytics en un contenedor Docker#

Aquí tienes cómo ejecutar el contenedor Docker de Ultralytics:

Link to this sectionUso exclusivo de la CPU#

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

Link to this sectionUso de 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:latest

El flag -it asigna un pseudo-TTY y mantiene stdin abierto, lo que te permite interactuar con el contenedor. El flag --ipc=host permite compartir el espacio de nombres IPC del host, algo esencial para compartir memoria entre procesos. El flag --device nvidia.com/gpu=... otorga al contenedor acceso a las GPUs del host a través de CDI.

Link to this sectionNota sobre la accesibilidad de archivos#

Para trabajar con archivos en tu máquina local dentro del contenedor, puedes utilizar volúmenes de 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

Reemplaza /path/on/host con la ruta del directorio en tu máquina local y /path/in/container con la ruta deseada dentro del contenedor Docker.

Link to this sectionPersistencia de las salidas de entrenamiento#

Las salidas de entrenamiento se guardan por defecto en /ultralytics/runs/<task>/<name>/ dentro del contenedor. Sin montar un directorio del host, las salidas se pierden cuando se elimina el contenedor.

Para persistir las salidas de entrenamiento:

# 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

Esto guarda todas las salidas de entrenamiento en ./runs en tu máquina host.

Link to this sectionEjecución de aplicaciones con interfaz gráfica de usuario (GUI) en un contenedor Docker#

Docker se utiliza principalmente para contenerizar aplicaciones de fondo y programas CLI, pero también puede ejecutar programas gráficos. En el mundo de Linux, dos servidores gráficos principales manejan la visualización gráfica: X11 (también conocido como X Window System) y Wayland. Antes de comenzar, es esencial determinar qué servidor gráfico estás utilizando actualmente. Ejecuta este comando para averiguarlo:

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

La configuración de un servidor de pantalla X11 o Wayland queda fuera del alcance de esta guía. Si el comando anterior no devuelve nada, deberás empezar por hacer que uno de los dos funcione en tu sistema antes de continuar.

Link to this sectionEjecución de un contenedor Docker con una GUI#

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

Link to this sectionUso de Docker con una GUI#

Ahora puedes mostrar aplicaciones gráficas dentro de tu contenedor Docker. Por ejemplo, puedes ejecutar el siguiente comando CLI para visualizar las predicciones de un modelo YOLO26:

yolo predict model=yolo26n.pt show=True

Link to this sectionCuando termines con la GUI de Docker#

xhost -local:docker

Ya tienes todo listo para usar Ultralytics con Docker y aprovechar sus capacidades. Para autohospedar la aplicación web de Ultralytics, consulta la guía de plataforma on-premise. Para otros métodos de instalación del paquete de Python, consulta la documentación de inicio rápido de Ultralytics.

Link to this sectionFAQ#

Link to this section¿Cómo configuro Ultralytics con Docker?#

Para configurar Ultralytics con Docker, primero asegúrate de que Docker esté instalado en tu sistema. Si tienes una GPU NVIDIA, instala el NVIDIA Container Toolkit para habilitar el soporte de GPU. Luego, descarga la última imagen de Docker de Ultralytics desde Docker Hub usando el siguiente comando:

sudo docker pull ultralytics/ultralytics:latest

Para conocer los pasos detallados, consulta nuestra Guía de inicio rápido de Docker.

Link to this section¿Cuáles son los beneficios de usar imágenes de Docker de Ultralytics para proyectos de aprendizaje automático?#

Usar imágenes de Docker de Ultralytics garantiza un entorno consistente en diferentes máquinas, replicando el mismo software y las mismas dependencias. Esto es particularmente útil para colaborar entre equipos, ejecutar modelos en varios tipos de hardware y mantener la reproducibilidad. Usa latest para entrenamiento general con GPU NVIDIA o selecciona la imagen que coincida con tu versión de JetPack para un dispositivo NVIDIA Jetson. Consulta la tabla completa de imágenes o explora Ultralytics Docker Hub.

Link to this section¿Cómo puedo ejecutar Ultralytics YOLO en un contenedor Docker con soporte para GPU?#

Primero, asegúrate de que el NVIDIA Container Toolkit esté instalado y configurado. Luego, usa el siguiente comando para ejecutar Ultralytics YOLO con soporte para GPU:

sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUs

Este comando configura un contenedor Docker con acceso a la GPU. Para obtener detalles adicionales, consulta la Guía de inicio rápido de Docker.

Link to this section¿Cómo visualizo los resultados de las predicciones de YOLO en un contenedor Docker con un servidor de pantalla?#

Para visualizar los resultados de las predicciones de YOLO con una GUI en un contenedor Docker, necesitas permitir que Docker acceda a tu servidor de pantalla. Para sistemas que ejecutan X11, el comando es:

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

Para sistemas que ejecutan 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:latest

Puedes encontrar más información en la sección Ejecución de aplicaciones con interfaz gráfica de usuario (GUI) en un contenedor Docker.

Link to this section¿Puedo montar directorios locales en el contenedor Docker de Ultralytics?#

Sí, puedes montar directorios locales en el contenedor Docker de Ultralytics usando la bandera -v:

sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Reemplaza /path/on/host con el directorio en tu máquina local y /path/in/container con la ruta deseada dentro del contenedor. Esta configuración te permite trabajar con tus archivos locales dentro del contenedor. Para obtener más información, consulta la sección Nota sobre la accesibilidad de archivos.