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.
• Asegúrate de que tu sistema tenga una GPU NVIDIA y que los controladores de NVIDIA estén instalados.
• Si utilizas dispositivos NVIDIA Jetson, asegúrate de tener instalada la versión de JetPack adecuada. Consulta la guía de NVIDIA Jetson para obtener más detalles.

Link to this sectionConfiguración de Docker con soporte para NVIDIA#

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 \
  nvidia-container-toolkit-base libnvidia-container-tools \
  libnvidia-container1

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Link to this sectionVerifica el tiempo de ejecución (runtime) de NVIDIA con Docker#

Ejecuta docker info | grep -i runtime para asegurarte de que nvidia aparece en la lista de entornos de ejecución:

docker info | grep -i runtime

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

Ultralytics ofrece varias imágenes de Docker optimizadas para diversas plataformas y casos de uso:

• Dockerfile: Imagen de GPU, ideal para el entrenamiento.
• Dockerfile-arm64: Para arquitectura ARM64, adecuada para dispositivos como Raspberry Pi.
• Dockerfile-cpu: Versión exclusiva para CPU para inferencia y entornos sin GPU.
• Dockerfile-jetson-jetpack4: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 4.
• Dockerfile-jetson-jetpack5: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 5.
• Dockerfile-jetson-jetpack6: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 6.
• Dockerfile-jupyter: Para desarrollo interactivo usando JupyterLab en el navegador.
• Dockerfile-nvidia-arm64: Para dispositivos NVIDIA ARM64 como Jetson AGX Thor y DGX Spark, compatible con JetPack 7.0 y DGX OS.
• Dockerfile-python: Entorno de Python mínimo para aplicaciones ligeras.
• Dockerfile-python-export: Imagen mínima de Python extendida con capacidades de exportación completas para la conversión de modelos YOLO.
• Dockerfile-conda: Incluye Miniconda3 y el paquete Ultralytics instalado vía Conda.
• Dockerfile-export: Imagen de GPU con todas las dependencias de formato de exportación preinstaladas para la conversión y evaluación comparativa de modelos.

Para descargar la última imagen:

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull $t

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 $t

Link to this sectionUso de GPUs#

# Run with all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus all $t

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t

La bandera -it asigna un pseudo-TTY y mantiene stdin abierto, lo que te permite interactuar con el contenedor. La bandera --ipc=host permite compartir el espacio de nombres IPC del host, esencial para compartir memoria entre procesos. La bandera --gpus permite que el contenedor acceda a las GPUs del host.

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 --runtime=nvidia --gpus all -v /path/on/host:/path/in/container $t

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 $t

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 configurado para usar Ultralytics con Docker y estás listo para aprovechar sus capacidades. Para otros métodos de instalación, 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?#

El uso de imágenes de Docker de Ultralytics garantiza un entorno consistente en diferentes máquinas, replicando el mismo software y dependencias. Esto es particularmente útil para colaborar entre equipos, ejecutar modelos en diversos hardware y mantener la reproducibilidad. Para el entrenamiento basado en GPU, Ultralytics proporciona imágenes de Docker optimizadas como Dockerfile para uso general de GPU y Dockerfile-jetson para dispositivos NVIDIA Jetson. Explora Ultralytics Docker Hub para obtener más detalles.

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 --runtime=nvidia --gpus 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 --runtime=nvidia --gpus 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.