Entrena tu primer modelo YOLO·Configuración·Lección 1/10

Lecciónprincipiante

Instala Ultralytics

Instala Ultralytics en un entorno limpio, lee el informe de comprobaciones de yolo para confirmar qué dispositivo usarás y verifica la configuración con una predicción.

Una ejecución de entrenamiento que pasa silenciosamente a la CPU puede tardar un día en vez de una hora, y no te darás cuenta hasta que sea demasiado tarde. Una instalación defectuosa da problemas de la misma forma: a mitad de una lección, con un error de importación o una GPU que no aparece.

Diez minutos aquí te evitarán ambos problemas. Instalarás el paquete ultralytics en un entorno nuevo, leerás línea por línea el informe yolo checks y ejecutarás una primera predicción de YOLO26 que comprobará que todo está conectado.

Resultado

Puedes instalar Ultralytics en un entorno limpio y saber, con una sola línea de yolo checks, si se ejecutará en CUDA, MPS o CPU.

Vía rápida

Si ya tienes experiencia, aquí tienes un resumen.

Crea y activa un entorno virtual nuevo con Python 3.10 o posterior.
En un equipo NVIDIA, instala primero PyTorch con CUDA y, después, pip install ultralytics.
Ejecuta yolo checks y lee el dispositivo al final de la primera línea.
Ejecuta yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg y abre la imagen guardada.

Práctico

Crea un entorno limpio#

El paquete ultralytics se instala en Python 3.8 y versiones posteriores, pero las versiones actuales de PyTorch necesitan Python 3.10 o posterior, así que empieza los proyectos nuevos con una versión reciente, como la 3.12. Un entorno virtual nuevo mantiene el paquete y sus dependencias separados de tus otros proyectos:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python --version                 # 3.10 or newer

La guía de inicio rápido de Ultralytics explica la misma configuración con Conda o Docker, si prefieres esas opciones.

Instala la versión adecuada de PyTorch y, después, Ultralytics#

Selector «Start Locally» de PyTorch, con opciones para elegir el sistema operativo, el gestor de paquetes, el lenguaje y la plataforma de computación para generar el comando de instalación de pip correspondiente

Ultralytics se ejecuta sobre PyTorch, y pip instala una compilación predeterminada de PyTorch si no hay ninguna presente. Esa compilación predeterminada es la causa principal de los problemas de «¿por qué está usando la CPU?», así que elige primero la compilación:

Tu equipo	Haz esto primero	Después
GPU NVIDIA	Instala la compilación con CUDA del selector de PyTorch que sea compatible con tu controlador	`pip install ultralytics` se encarga de ello
Mac con Apple Silicon	Nada: la compilación predeterminada incluye MPS	`pip install ultralytics`
Solo CPU	Nada	`pip install ultralytics`

pip install ultralytics

Ese único comando instala el paquete de Python ultralytics, la herramienta de línea de comandos yolo y dependencias como OpenCV y NumPy.

Lee el informe `yolo checks`#

yolo checks muestra las versiones y el hardware que utilizará Ultralytics. Salida real de un MacBook, abreviada:

Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)

OS                     macOS-27.0.1-arm64-arm-64bit
Python                 3.12.12
Install                pip
GPU                    None

Línea por línea:

Ultralytics 8.4.175 ... torch-2.14.1: las versiones del paquete y de PyTorch. Indícalas en cualquier informe de errores.
CPU (Apple M5 Pro): el dispositivo que se utiliza cuando no especificas device. Esta es la línea importante.
Setup complete ✅: la instalación está en buen estado.
GPU None: PyTorch no detecta ninguna GPU CUDA. Es lo esperado en un Mac, pero un problema en un equipo NVIDIA.

Actúa según el dispositivo indicado en la primera línea:

No necesitas una GPU para este curso: todos los ejemplos están dimensionados para terminar en cuestión de minutos en la CPU de un portátil. Una GPU es importante cuando entrenas a tamaño completo, ya que suele ser al menos 10 veces más rápida.

Compruébalo con una predicción#

Una predicción pone a prueba toda la pila: descarga los pesos nano de YOLO26, obtiene una imagen, ejecuta el modelo y guarda una copia anotada.

yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict

640x480 4 persons, 1 bus: la imagen se ha redimensionado a 640×480 para el modelo, que ha detectado cinco objetos.
20.1ms: tiempo de inferencia en esta CPU. Anota el tuyo; será tu primera referencia de velocidad.
runs/detect/predict: indica dónde se ha guardado bus.jpg anotada. Si vuelves a ejecutar el comando, obtendrás predict-2: Ultralytics nunca sobrescribe una ejecución anterior.

Todos los valores predeterminados de ese comando —confianza, tamaño de imagen y ubicación de guardado— aparecen en la referencia de configuración.

Soluciona los problemas más habituales#

Entrenar silenciosamente en la CPU

Síntoma: yolo checks muestra CPU y GPU None en una máquina con una GPU NVIDIA, y el entrenamiento es desesperantemente lento. Causa: pip ha instalado una versión de PyTorch solo para CPU. Solución: desinstala torch y torchvision, instala la versión de CUDA desde el selector de PyTorch y vuelve a ejecutar yolo checks hasta que la primera línea indique CUDA:0.

yolo: comando no encontrado

Causa: el entorno virtual no está activo en este terminal, así que el script yolo no está en tu PATH. Solución: ejecuta source .venv/bin/activate (o su equivalente en Windows) en cada terminal nuevo antes de usar yolo.

Síntoma	Causa	Solución
`requirements: ... not found, attempting AutoUpdate` y, después, `No module named pip`	El entorno se ha creado sin pip, por lo que Ultralytics no puede instalar automáticamente un paquete adicional	Instala el paquete indicado con la herramienta de tu entorno, por ejemplo, `uv pip install lap`
Las descargas de pesos o del conjunto de datos agotan el tiempo de espera	La red bloquea los recursos de las versiones de GitHub	Descarga `yolo26n.pt` una vez desde otro sitio y especifica su ruta local
`PermissionError` está escribiendo `runs/`	El directorio de trabajo es de solo lectura	`cd` en una carpeta de proyecto con permisos de escritura

Para cualquier otro problema, la guía de problemas habituales recopila soluciones conocidas, y las incidencias cerradas del repositorio de Ultralytics suelen tener la respuesta: búscalas antes de abrir una nueva.

Pruébalo

En un entorno nuevo, instala Ultralytics, ejecuta yolo checks y ejecuta la predicción del autobús. Entrega un registro de configuración de tres líneas: tus versiones de Ultralytics y PyTorch, el dispositivo indicado en la primera línea de yolo checks (y, en un equipo NVIDIA, una prueba de que indica CUDA:0) y el tiempo de inferencia indicado para bus.jpg.

Cuándo se considera terminado

Has terminado la lección cuando se cumplen todas estas condiciones.

yolo checks termina con Setup complete ✅ e indica el dispositivo que esperas.
Existe runs/detect/predict/bus.jpg con cuatro personas y un autobús dentro de cuadros.
Has anotado tus versiones, el dispositivo y el tiempo de inferencia de bus.jpg.

Mostrar solución

python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

Versions: Ultralytics 8.4.175, torch 2.14.1
Device:   CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg:  20.1 ms inference at 640x480

En la CPU de un portátil, espera unos 10–60 ms para bus.jpg; en una GPU NVIDIA reciente, unos pocos milisegundos. Si yolo checks indica el dispositivo equivocado, corrige PyTorch antes de continuar.

Qué viene después

El entorno funciona. Ahora ejecuta la misma predicción desde Python y aprende a leer todos los campos que devuelve el modelo.

Inicia sesión para guardar tu progreso

Get Started