Guía de inicio rápido de Docker para Ultralytics#

Esta guía ofrece una introducción completa a la configuración de un entorno Docker para tus proyectos de Ultralytics. Docker es una plataforma para desarrollar, distribuir y ejecutar aplicaciones en contenedores. Resulta especialmente útil para garantizar que el software se ejecute siempre de la misma forma, independientemente de dónde se implemente. Para obtener más información, visita el repositorio de Docker de Ultralytics en Docker Hub.

Qué aprenderás#

• Configurar Docker con compatibilidad con NVIDIA
• Instalar imágenes Docker de Ultralytics
• Ejecutar Ultralytics en un contenedor Docker con compatibilidad con CPU o GPU
• Usar un servidor de pantalla con Docker para mostrar los resultados de detección de Ultralytics
• Montar directorios locales en el contenedor

Requisitos 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 mediante GPU, asegúrate de que tu sistema tenga una GPU NVIDIA y los controladores de NVIDIA instalados. Las imágenes para CPU no requieren hardware 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 información.

Configurar Docker con compatibilidad con NVIDIA (opcional)#

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

nvidia-smi

Instalar NVIDIA Container Toolkit#

Ahora, instala el NVIDIA Container Toolkit para habilitar la compatibilidad con 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

Verificar dispositivos CDI con Docker#

Ejecuta nvidia-ctk cdi list para asegurarte de que los dispositivos GPU de CDI estén disponibles (el servicio nvidia-cdi-refresh del kit de herramientas genera y mantiene la especificación automáticamente en 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.

Instalar imágenes Docker de Ultralytics#

Ultralytics publica las siguientes imágenes en Docker Hub. Cada imagen se compila a partir de su Dockerfile enlazado mediante el flujo de trabajo de publicación de Docker.

Las imágenes de GPU AMD64 (latest, latest-export y latest-runner) utilizan PyTorch 2.14 y CUDA 13.2. Comprueba la compatibilidad con CUDA del controlador del host con nvidia-smi antes de iniciarlas; instalar un contenedor más nuevo no actualiza el controlador del host. CUDA 13 elimina la compatibilidad con las GPU Maxwell, Pascal y Volta, incluidas Tesla P100 y V100. Consulta las notas de la versión de CUDA de NVIDIA y los requisitos de compatibilidad de controladores.

La imagen NVIDIA ARM64 utiliza NVIDIA PyTorch 26.08 con CUDA 13.4 y TensorRT 11.2. La compatibilidad de PyTorch con Thor no se extiende a TensorRT: NVIDIA no admite TensorRT 11.2 en JetPack. Para las exportaciones de Jetson TensorRT, utiliza el tiempo de ejecución compatible de TensorRT 10.x para tu versión de JetPack. Sigue los requisitos de la plataforma en la guía de Jetson o en la guía de DGX Spark. Las imágenes de JetPack 4, 5 y 6 conservan sus pilas independientes específicas de cada dispositivo.

El Dockerfile de Conda está disponible para compilaciones locales; la publicación automatizada de latest-conda está desactivada, por lo que esa etiqueta del registro no contiene estas actualizaciones.

Utiliza latest-python-export para las exportaciones de LiteRT. La imagen de GPU latest-export mantiene PyTorch 2.14 y omite LiteRT porque su dependencia actual requiere una versión de PyTorch inferior a la 2.14.

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

Para extraer la imagen más reciente:

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

Para compilar una imagen tú mismo, clona el repositorio y proporciona el Dockerfile correspondiente de la tabla anterior, usando la raíz del repositorio como contexto de compilación:

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Ejecutar Ultralytics en un contenedor Docker#

Así puedes ejecutar el contenedor Docker de Ultralytics:

Usar únicamente la CPU#

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

Usar 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

La opción -it asigna una pseudo-TTY y mantiene stdin abierto, lo que te permite interactuar con el contenedor. La opción --ipc=host habilita el uso compartido del espacio de nombres IPC del host, algo esencial para compartir memoria entre procesos. La opción --device nvidia.com/gpu=... concede al contenedor acceso a las GPU del host mediante CDI.

Nota sobre la accesibilidad de los archivos#

Para trabajar con archivos de tu máquina local desde el contenedor, puedes usar 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

Sustituye /path/on/host por la ruta del directorio de tu máquina local y /path/in/container por la ruta deseada dentro del contenedor Docker.

Conservar los resultados del entrenamiento#

De forma predeterminada, los resultados del entrenamiento se guardan en /ultralytics/runs/<task>/<name>/ dentro del contenedor. Si no montas un directorio del host, los resultados se perderán al eliminar el contenedor.

Para conservar los resultados del 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 todos los resultados del entrenamiento en ./runs de tu máquina host.

Ejecutar aplicaciones de interfaz gráfica de usuario (GUI) en un contenedor Docker#

Docker se utiliza principalmente para contenerizar aplicaciones en segundo plano y programas CLI, pero también puede ejecutar programas gráficos. En el entorno Linux, hay dos servidores gráficos principales que gestionan la pantalla: X11 (también conocido como el sistema de ventanas X) y Wayland. Antes de empezar, 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 y el ajuste de un servidor de pantalla X11 o Wayland quedan fuera del alcance de esta guía. Si el comando anterior no devuelve nada, primero tendrás que conseguir que uno de ellos funcione en tu sistema antes de continuar.

Ejecutar un contenedor Docker con una interfaz gráfica de usuario#

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

Usar Docker con una interfaz gráfica de usuario#

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

Al terminar de usar la interfaz gráfica de Docker#

xhost -local:docker

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

Preguntas frecuentes#