Arrancar una Raspberry Pi sin monitor, teclado ni ratón —lo que se conoce como modo headless— ha sido siempre más complicado de lo que debería. La solución habitual pasa por configurar previamente la red Wi-Fi, habilitar SSH y rezar para que el router le asigne la IP que esperas. Cuando algo falla, el único recurso suele ser enchufar una pantalla y un teclado, que es exactamente lo que se quería evitar.
El modo gadget USB ya existía como alternativa. El problema era la puesta en marcha: editar ficheros de arranque a mano, instalar scripts de terceros y repetir el proceso de forma distinta según el sistema operativo del anfitrión. En enero de 2026, la Fundación Raspberry Pi anunció oficialmente el paquete rpi-usb-gadget. Su incorporación en Raspberry Pi OS cerró de un plumazo años de soluciones a medio gas.
Qué es el modo gadget USB
En modo gadget USB, un dispositivo se presenta ante el ordenador como un periférico. De esta forma, en lugar de actuar como anfitrión de otros dispositivos, es él quien obedece al ordenador anfitrión. En el caso de la Raspberry Pi, el resultado es que el ordenador la reconoce como una tarjeta de red Ethernet adicional, exactamente igual que ocurre cuando conectas el móvil por USB para compartir su conexión.
Con eso, un único cable proporciona alimentación eléctrica y enlace de red. El tráfico SSH circula por ese mismo cable sin necesidad de router, Wi-Fi ni Ethernet separado. La tecnología de base es el módulo g_ether del kernel Linux. Expone una interfaz virtual con los perfiles CDC-ECM y RNDIS, compatibles con macOS, Linux y Windows.
El requisito hardware imprescindible es que el puerto USB soporte OTG. Esta norma es la que permite a un puerto cambiar de rol entre anfitrión y dispositivo. No todos los puertos de la Raspberry Pi lo permiten.
Qué aporta rpi-usb-gadget
El paquete rpi-usb-gadget automatiza todo lo que antes se hacía a mano. Instala un servicio en segundo plano que arranca con el sistema y gestiona de forma automática dos modos de funcionamiento. Si el ordenador anfitrión tiene activo ICS, la Raspberry Pi actúa como cliente DHCP y recibe una IP del anfitrión. Por ese mismo cable llega también el acceso a Internet. Si no hay ICS activo, la Raspberry Pi adopta el modo independiente y proporciona ella misma dirección IP al anfitrión. El cambio entre ambos modos es automático y no requiere intervención.
Una vez el sistema ha arrancado, basta con abrir un terminal en el ordenador y ejecutar:
ssh usuario@nombre-del-host.localEl nombre de host es el que se configuró en Raspberry Pi Imager antes de grabar la imagen. La resolución del nombre funciona mediante mDNS, disponible de serie en macOS y Linux. En Windows puede ser necesario instalar Bonjour o usar directamente la IP asignada.
Modelos compatibles
El modo gadget funciona en los modelos que disponen de un puerto USB con capacidad OTG. La lista cubre la Raspberry Pi 3 Model A+, la Pi 4 Model B, la Pi 5, la Pi 500, la Pi 500+ y toda la familia Zero (Zero, Zero W y Zero 2 W). El Compute Module 5 también es compatible. El Compute Module 4 está soportado pero requiere pasos adicionales de configuración. En los modelos Pi 4, Pi 5 y Pi 500 el puerto correcto es el USB-C. En los modelos Zero es el micro-USB más cercano al conector mini-HDMI.
Cómo activarlo con Raspberry Pi Imager 2.0
Imager 2.0 introdujo un cambio importante respecto a versiones anteriores: antes de mostrar las opciones de personalización, necesita saber qué capacidades tiene la imagen seleccionada. Esa información viaja en un fichero tipo «manifest» que el propio Imager descarga al arrancar. La capacidad usb_otg no está activada en el manifiesto oficial por defecto. Mientras no se genere un manifiesto personalizado, el toggle no aparece en Imager.
El proceso requiere tener Python 3 instalado en el ordenador y acceso a internet. El script necesario se encuentra en el repositorio oficial de Imager. Hay que clonar el repositorio o descargar únicamente el fichero create_local_json.py desde github.com/raspberrypi/rpi-imager. Una vez descargado, se ejecuta desde la terminal en el directorio donde esté el script:
./create_local_json.py --online --capabilities usb_otg --device-capabilities usb_otgEl flag --online descarga el catálogo de imágenes oficiales directamente desde los servidores de Raspberry Pi. Los flags --capabilities y --device-capabilities añaden usb_otg tanto al sistema operativo como al perfil del dispositivo. Ambos son necesarios para que Imager muestre la opción en el menú de personalización. El script genera un fichero llamado os_list_local.rpi-imager-manifest en el directorio actual. Si se prefiere guardarlo en otro lugar, se usa el flag adicional --output-json /ruta/de/destino/os_list_local.rpi-imager-manifest.
Una vez generado el fichero hay que activarlo en las opciones de Raspberry Pi Imager como se ven en las imágenes siguientes.
A partir de ahí el proceso es el habitual pero con ese opción ya disponible al final:
- Seleccionar el dispositivo Raspberry Pi.
- Elegir una imagen de Raspberry Pi OS Trixie con fecha 20/10/2025 o posterior.
- Abrir el menú de personalización, habilitar SSH y establecer nombre de usuario, contraseña y nombre de host. El nombre de host es el que se usará para conectarse por SSH con
nombre.local. Si el ordenador anfitrión no tiene ICS activo, la IP de reserva será10.12.194.1. - En la pestaña Interfaces & Features, activar USB Gadget Mode.
- Grabar la imagen en la tarjeta.
El primer arranque puede tardar algo más de lo habitual e incluir un reinicio automático. Es comportamiento esperado. En los modelos Zero es especialmente importante configurar el usuario y las claves SSH en este paso. Con el modo gadget activo el puerto USB queda ocupado y no es posible conectar teclado ni ratón después.
En una instalación Trixie existente
En una Raspberry Pi ya en marcha con Raspberry Pi OS basado en Trixie, la instalación se reduce a dos comandos desde la terminal:
sudo apt update
sudo apt install rpi-usb-gadgetDespués hay que habilitar el modo desde raspi-config y reiniciar. Al reiniciar, la sesión SSH activa se desconectará brevemente. La reconexión es automática en cuanto la interfaz de red USB está disponible.
Conectarse desde el ordenador anfitrión
Windows
Windows no incluye controlador nativo para dispositivos Ethernet USB de este tipo. El primer paso es instalar el paquete rpi-usb-gadget-driver-setup.exe, disponible en el repositorio oficial del proyecto. Esta instalación es única por ordenador. Para compartir Internet hay que activar ICS en el adaptador con acceso a la red —normalmente Wi-Fi—. Después se asigna ese adaptador al de la Raspberry Pi. Windows asigna la dirección 192.168.137.1 al adaptador USB y la Raspberry Pi obtiene una IP en ese rango. Si el nombre de host no resuelve con .local, se puede usar la IP directa visible con arp -a.
macOS
macOS reconoce el adaptador USB de forma nativa. Para compartir Internet, ir a Ajustes del sistema → General → Compartir. Allí se activa la opción de compartir conexión desde el adaptador Wi-Fi hacia el de la Raspberry Pi. La conexión SSH con nombre-del-host.local funciona sin instalar nada adicional.
Linux
El soporte es nativo a través de NetworkManager o las herramientas de red equivalentes. Para compartir Internet hay que configurar el enrutamiento y NAT entre la interfaz principal y la interfaz USB de la Raspberry Pi. El procedimiento exacto depende de la distribución y de la pila de red en uso. La documentación del proyecto en GitHub recoge ejemplos para los casos más habituales.
La limitación que hay que tener clara
Una vez activado el modo gadget, el puerto USB utilizado queda reservado exclusivamente para alimentación y conexión de red. No es posible conectar a ese puerto un teclado, un ratón ni una unidad de almacenamiento mientras el modo esté activo. Para recuperar el puerto como anfitrión hay que desactivar el modo gadget y reiniciar.
En los modelos Zero esto tiene una implicación importante. Con el modo activo no es posible conectar ningún periférico USB. Por eso es imprescindible haber configurado el usuario y las claves SSH desde Raspberry Pi Imager antes de grabar la imagen: el asistente de configuración inicial no es accesible por SSH.
