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 funcione siempre igual, 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 lo está, puedes descargarlo e instalarlo desde el sitio web de Docker.
• Para acelerar el procesamiento con GPU, asegúrate de que tu sistema tenga una GPU NVIDIA y los controladores NVIDIA instalados. Las imágenes para 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 información.

Configurar Docker con compatibilidad con NVIDIA (opcional)#

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

nvidia-smi

Instalar NVIDIA Container Toolkit#

Ahora vamos a instalar 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 comprobar que los dispositivos CDI de GPU están disponibles (el servicio nvidia-cdi-refresh del kit de herramientas genera y mantiene automáticamente la especificación 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. La automatización de publicación de Docker compila cada imagen a partir del Dockerfile enlazado.

Las imágenes GPU AMD64 (latest, latest-export y latest-runner) usan PyTorch 2.14 y CUDA 13.2. Comprueba la compatibilidad del controlador del host con CUDA mediante nvidia-smi antes de iniciarlas; instalar un contenedor más reciente no actualiza el controlador del host. CUDA 13 deja de ser compatible 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 los controladores.

La imagen NVIDIA ARM64 usa 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 TensorRT en Jetson, usa el entorno de ejecución TensorRT 10.x compatible con 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 para 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.

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

Las imágenes Python, CPU, Jupyter y ejecutor de CPU usan Python 3.14. La imagen de exportación de Python usa la base latest-python-3.13, creada a partir de la misma Dockerfile-python con --build-arg PYTHON_VERSION=3.13, porque TensorFlow, CoreML y PaddlePaddle aún no son compatibles con Python 3.14.

Las etiquetas que empiezan por latest corresponden a la compilación publicada más reciente de la rama principal. En las etiquetas con versión, el prefijo latest se sustituye por una versión de Ultralytics, como VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Usa una etiqueta con versión para obtener un entorno reproducible.

Para descargar la imagen más reciente:

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

Si prefieres compilar una imagen tú mismo, clona el repositorio y pasa el Dockerfile correspondiente de la tabla anterior; usa 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#

A continuación se explica cómo ejecutar el contenedor Docker de Ultralytics:

Usar solo 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 un 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. Para GPU NVIDIA, la opción --device nvidia.com/gpu=... concede acceso mediante CDI. Para GPU AMD, las opciones --device conceden acceso al controlador del núcleo de la GPU (/dev/kfd) y a los nodos de representación de pantalla (/dev/dri).

Nota sobre el acceso a los archivos#

Para trabajar con archivos de tu equipo local desde el contenedor, puedes usar volúmenes 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 equipo 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 pierden 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 en tu equipo 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 de CLI, pero también puede ejecutar programas gráficos. En el entorno Linux, hay dos servidores gráficos principales que gestionan la visualización: X11 (también conocido como X Window System) y Wayland. Antes de empezar, es fundamental determinar qué servidor gráfico estás usando. Ejecuta este comando para averiguarlo:

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

La configuración de un servidor de visualización X11 o Wayland queda 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 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

Usar Docker con una GUI#

Las imágenes de Ultralytics incluyen OpenCV sin interfaz gráfica, así que instala primero la versión de OpenCV con interfaz gráfica y sus bibliotecas del sistema dentro del contenedor:

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

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

yolo predict model=yolo26n.pt show=True

Cuando termines de usar la GUI de Docker#

xhost -local:docker

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

Preguntas frecuentes#