Docker Desktop no se conecta a WSL 2: solucionar el CLI, el inicio del motor y la integración

Diagnostica problemas de Docker Desktop y WSL 2 en Windows, las distribuciones Linux y Docker Engine. Resuelve comandos docker ausentes, fallos de conexión e inicio de WSL, ajustes de integración y montajes.

Si docker funciona en una terminal de Windows, pero Ubuntu muestra command not found, probablemente esa distribución no tiene habilitada la integración WSL de Docker Desktop. Si el comando existe, pero devuelve Cannot connect to the Docker daemon, comprueba primero si Docker Desktop está iniciado, qué Docker context está activo y si está definida la variable DOCKER_HOST. Usa comandos de solo lectura para identificar la capa que falla antes de seguir los pasos correspondientes. No empieces restableciendo los datos de Docker ni anulando el registro de una distribución WSL.

Esta guía cubre Docker Desktop, distribuciones Linux con WSL 2 y flujos de trabajo con contenedores Linux en Windows. El backend WSL 2, Docker VMM e Hyper-V de Docker Desktop se comportan de forma diferente; confirma cuál utilizas. El modo de contenedores Windows también es distinto del entorno Linux descrito aquí.

Identifica si falla Windows, WSL o Docker Engine

Empieza por recopilar el estado básico en Windows PowerShell:

1
2
3
4
5
6
wsl --status
wsl --version
wsl --list --verbose
Get-Command docker -ErrorAction SilentlyContinue
docker context show
docker version

Estos comandos no modifican contenedores ni distribuciones. wsl --list --verbose muestra si cada distribución usa WSL 1 o WSL 2. docker version separa la información de Client y Server. Si solo aparece Client, el CLI se encontró, pero no se conectó al motor.

Después abre la distribución Linux que usas para desarrollar y compruébalo allí:

1
2
3
4
5
printf 'distro=%s\n' "$WSL_DISTRO_NAME"
command -v docker || true
type -a docker 2>/dev/null || true
docker context show
docker version

Compara ambos resultados para distinguir entre «Windows no encuentra el programa», «la distribución no recibió el CLI» y «el motor no responde».

Confirma que WSL funciona por sí solo

Si wsl --status, wsl -l -v o el inicio de Ubuntu falla, diagnostica primero WSL y la virtualización de Windows. Todavía no cambies los ajustes de Docker Desktop.

Docker indica actualmente que el backend WSL 2 de Docker Desktop requiere como mínimo WSL 2.1.5 y recomienda mantener WSL actualizado. Comprueba la versión instalada:

1
2
3
wsl --version
wsl --status
wsl --list --verbose

Si WSL está desactualizado, guarda los archivos que estés editando y después actualiza y reinicia la máquina virtual de WSL:

1
2
wsl --update
wsl --shutdown

wsl --shutdown detiene inmediatamente todas las distribuciones WSL en ejecución. Abre Ubuntu otra vez y comprueba wsl -l -v; la columna VERSION de la distribución objetivo debería indicar 2. Si indica 1, no la conviertas sin guardar una copia de seguridad de los archivos importantes. La conversión puede tardar y fallar.

Si falla la actualización de WSL, revisa Microsoft Store, Windows Update y las políticas de red. wsl --update --web-download cambia a una descarga web. No fuerces el apagado de Windows durante la actualización ni uses wsl --unregister como si fuera un comando de reinicio normal.

Asegúrate de que Docker Desktop se ejecuta en modo de contenedores Linux

Comprueba en la bandeja del sistema de Windows que Docker Desktop haya terminado de iniciar. Si sigue mostrando Starting o Docker Engine is starting, o aparece un error del motor, anota el mensaje completo. La opción “Switch to Linux containers” en el menú de la bandeja puede indicar que estás en modo de contenedores Windows. El desarrollo con contenedores Linux en WSL requiere el modo Linux.

La opción de integración WSL solo aparece con un backend y un modo de contenedores compatibles. Si Docker Desktop usa el motor WSL 2, abre Settings > General y comprueba “Use the WSL 2 based engine”. Luego ve a Settings > Resources > WSL Integration, activa las distribuciones necesarias y selecciona Apply.

Si tienes varias distribuciones, la predeterminada puede no ser la que abriste. Ejecuta wsl -l -v, identifica el nombre exacto y activa esa distribución en la página de integración. Para cambiar la distribución predeterminada:

1
wsl --set-default Ubuntu

Sustituye Ubuntu por el nombre exacto de la lista. Cambiar la distribución predeterminada afecta a los comandos WSL que no especifican una distribución. No convierte las demás a WSL 2 ni mueve sus archivos.

WSL indica que no existe el comando docker

Si docker version funciona en Windows PowerShell, pero la distribución Linux devuelve command not found, comprueba estos puntos en orden:

  1. Confirma en wsl -l -v que la distribución objetivo usa la versión 2.
  2. Activa el motor WSL 2 en los ajustes de Docker Desktop.
  3. Activa la distribución actual en Settings > Resources > WSL Integration.
  4. Selecciona Apply y espera a que Docker Desktop aplique el cambio.
  5. Ejecuta wsl --shutdown en Windows y vuelve a abrir la distribución.
  6. Dentro de la distribución, ejecuta command -v docker y docker version.

No instales otro Docker Engine dentro de la distribución solo porque falte el comando. Docker advierte que instalar Docker Engine o Docker CLI directamente en una distribución WSL puede entrar en conflicto con la integración de Docker Desktop. Dos instalaciones también pueden hacer que el CLI use otro daemon y que la lista de contenedores de Ubuntu no coincida con la de Windows.

Ejecutar un motor independiente dentro de Linux es otra opción de despliegue. Decide expresamente quién administra el daemon, el directorio de datos, el servicio de inicio y el Docker context. Evita que dos motores compitan por los mismos comandos de desarrollo.

El comando existe, pero no puede conectarse a Docker daemon

Confirma que Docker Desktop terminó de iniciarse en Windows y ejecuta:

1
2
3
docker context ls
docker context show
docker version

Si el context actual apunta a un host remoto por SSH u otro endpoint, docker quizá no esté usando el Desktop local. Después de confirmarlo, cambia al context de Desktop. No sobrescribas la configuración de Docker a ciegas: un context remoto puede ser intencional.

En WSL, comprueba si las variables de entorno sustituyen la dirección de conexión:

1
2
3
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)=' || true
docker context ls
docker context show

DOCKER_HOST puede obligar al CLI a usar un socket o una dirección TCP específicos. DOCKER_CONTEXT puede seleccionar otro context. Anota los valores y su origen antes de decidir si los quitas temporalmente de la terminal actual. En PowerShell, inspecciona:

1
Get-ChildItem Env:DOCKER_HOST,Env:DOCKER_CONTEXT -ErrorAction SilentlyContinue

No uses sudo docker como solución general. Puede cargar la configuración y el context de root y conectarse a otro daemon. Ante un error de permisos, identifica primero qué CLI y motor están implicados.

Si Docker Desktop todavía está iniciando, repetir comandos de Compose solo repite el fallo. Espera a que Dashboard indique que el motor está listo y confirma la información de Server con docker version antes de ejecutar comandos del proyecto.

El comando conecta, pero muestra contenedores inesperados

Normalmente, esto significa que el CLI se conectó a otro motor. Comprueba los context y la resolución del ejecutable:

1
2
3
4
Get-Command docker -All
where.exe docker
docker context ls
docker context show

En WSL, ejecuta:

1
2
3
type -a docker
command -v docker
env | grep -E '^DOCKER_(HOST|CONTEXT|TLS|CERT_PATH)=' || true

Si type -a docker muestra varias rutas, identifica cuál es el primer ejecutable. Pueden coexistir el CLI de Docker Desktop disponible mediante el PATH de Windows, un CLI instalado en la distribución y un alias de shell. Identifica su origen antes de borrar archivos o cambiar el PATH del sistema.

Los contenedores, imágenes y volúmenes pertenecen a sus respectivos motores. Es normal que docker ps -a o docker volume ls muestren resultados distintos después de cambiar el context. Confirma el endpoint antes de borrar nada; no confundas un context remoto de producción con un motor de pruebas local.

Aparece un error inesperado de WSL o no inicia la máquina virtual

Si el error incluye HCS_E_HYPERV_NOT_INSTALLED o ERROR_NOT_SUPPORTED, o WSL tampoco puede iniciar una distribución, revisa primero las características de Windows y la virtualización del hardware:

  • ¿Está activada la virtualización de CPU en BIOS/UEFI?
  • ¿Están habilitados Virtual Machine Platform y Windows Subsystem for Linux en Windows?
  • Si Windows se ejecuta dentro de una VM o un escritorio en la nube, ¿el host tiene habilitada la virtualización anidada?
  • ¿Se desactivó el hipervisor en el arranque o con otro software de virtualización?
  • ¿Se instaló recientemente un emulador de Android o una VM antigua que pudo cambiar la configuración de Hyper-V?

Task Manager, en Performance > CPU, muestra el estado de virtualización. No cambies BCD ni las características de Windows sin entender la configuración de las máquinas virtuales. En un equipo administrado, comprueba primero las políticas de la organización.

Si wsl -l -v funciona, pero solo falla la distribución docker-desktop, guarda el error completo y la hora, y recopila diagnósticos desde Docker Desktop > Troubleshoot > Get support. No elimines manualmente docker-desktop ni docker-desktop-data, y no ejecutes comandos de limpieza dentro de ellas.

Falta el menú de integración WSL o la distribución seleccionada sigue fallando

Confirma que Docker Desktop no está en modo de contenedores Windows e identifica el backend. Docker indica que WSL Integration completa solo está disponible con el motor WSL 2. En modo Docker VMM, versiones recientes permiten usar el CLI desde distribuciones WSL, pero los límites de socket, montajes directos y herramientas de desarrollo son diferentes.

Antes de cambiar el backend, consulta los ajustes de tu versión de Docker Desktop y confirma qué funciones necesita tu equipo. Que docker funcione no garantiza la compatibilidad con VS Code Dev Containers, Docker SDK o Testcontainers, que usan el socket de la API de Docker Engine.

Si acabas de activar la integración y la terminal conserva el entorno anterior, ejecuta:

1
wsl --shutdown

Luego vuelve a abrir la distribución objetivo. Esto cierra todas las distribuciones y la máquina virtual de WSL. No restablece los archivos, pero interrumpe el estado no guardado de los procesos.

No alternes entre WSL 1 y 2, anules el registro de una distribución, restablezcas Docker Desktop a los valores de fábrica ni borres un disco virtual solo para actualizar la integración. Estas acciones pueden provocar pérdida de datos y normalmente no hacen falta en la primera ronda de diagnóstico.

En Docker VMM funciona el comando, pero fallan los montajes o las herramientas

Docker VMM y el motor WSL 2 interactúan de forma diferente. En modo VMM, WSL puede llamar al CLI de Docker mediante la interoperabilidad con Windows. La documentación actual señala limitaciones: no hay un socket Docker Linux y solo se pueden montar directamente archivos de unidades de Windows. Herramientas como Docker SDK, Testcontainers y Dev Containers que dependen del socket pueden no funcionar.

Un proyecto iniciado en PowerShell suele usar una ruta C:\...; la misma unidad de Windows aparece como /mnt/c/... en WSL. Si el error menciona una ruta dentro de la distribución, como /home/..., y usas Docker VMM, confirma que ese flujo sea compatible. Cambiar una ruta Linux por una de Windows no garantiza los mismos permisos, la vigilancia de archivos ni el rendimiento.

Para desarrollar en Linux con el motor WSL 2, Docker recomienda guardar el proyecto en el sistema de archivos de la distribución para reducir las operaciones entre sistemas de archivos. Si las herramientas de Windows y los contenedores Linux acceden con frecuencia al mismo proyecto, evalúa permisos, distinción entre mayúsculas y minúsculas, vigilancia de archivos y rendimiento de montaje antes de elegir un espacio de trabajo principal.

Si falla un montaje, comprueba que la ruta de origen exista, desde qué directorio se ejecuta el comando, qué backend está activo y si la distribución tiene la integración habilitada. Distingue la ruta del contenedor /app, la de Windows C:\project y la de WSL /mnt/c/project.

WSL tiene una distribución, pero Docker Desktop no la encuentra

Vuelve a enumerar las distribuciones desde Windows y revisa la columna de versión:

1
2
wsl --list --verbose
wsl --list --quiet

Si el nombre contiene espacios o cambia el uso de mayúsculas, selecciona el nombre exacto de la salida. Una distribución nueva puede usar WSL 1 de forma predeterminada; la integración WSL 2 de Docker Desktop requiere una distribución WSL 2. Haz una copia de seguridad antes de convertirla:

1
2
wsl --export Ubuntu "$env:USERPROFILE\Desktop\Ubuntu-backup.tar"
wsl --set-version Ubuntu 2

La exportación contiene los datos de la distribución y puede ocupar mucho espacio. Confirma que el archivo existe y es accesible antes de convertirla. No uses el nombre de ejemplo si tu distribución importante tiene otro nombre.

Si cambiaste el nombre, moviste o importaste una distribución, comprueba el nombre registrado y el estado con wsl -l -v. No borres entradas de registro para hacer que “vuelva a aparecer”. El registro, el archivo de disco de la distribución y el disco virtual que administra Docker Desktop son objetos diferentes.

La integración deja de funcionar tras actualizar Docker Desktop

No elimines inmediatamente todas las imágenes y contenedores después de una actualización. Anota la versión de Docker Desktop, wsl --version, el nombre de la distribución, el backend y el error completo. Después revisa las notas de versión oficiales de Docker para buscar una combinación coincidente.

Las notas recientes de Docker documentaron un problema en el que la integración con distribuciones de usuario fallaba en WSL 2.6.x y posteriores por un proxy binario de cero bytes, con errores Permission denied o Exec format error. Una versión posterior lo corrigió. Si el error coincide, comprueba la versión real de Docker Desktop y el canal de actualización. No sustituyas archivos internos siguiendo instrucciones de foros no verificadas.

Las mismas notas documentan una corrección para el CLI de Docker en distribuciones integradas que dejaba de funcionar temporalmente después de que Resource Saver detuviera la máquina virtual. La aplicabilidad depende de las versiones instaladas. Un Diagnostic ID y unos pasos reproducibles son más útiles que una suposición basada en una palabra clave.

Para reducir la reproducción, cierra Docker Desktop, ejecuta wsl --shutdown, reinicia Docker Desktop, espera a que el motor esté listo, abre una sola distribución objetivo y ejecuta docker version. Anota la hora y el resultado en cada paso. Si falla solo una distribución, céntrate en ella; si fallan todos los comandos WSL, vuelve a revisar WSL y las características de Windows.

Cambia un ajuste cada vez. Por ejemplo, actualiza WSL y comprueba el resultado antes de cambiar el backend de Docker Desktop. Actualizar WSL, cambiar entre Hyper-V y VMM, restablecer los datos y reinstalar todo a la vez elimina pistas causales y puede introducir variables nuevas.

Si sospechas una regresión, comprueba la versión en la pantalla About de Docker Desktop y las fechas de las notas oficiales antes de decidir una actualización o reversión según la política de tu organización. No descargues instaladores antiguos de fuentes desconocidas ni sobrescribas archivos internos de docker-desktop con scripts de foros.

Un error al descargar imágenes no siempre es un problema de integración WSL

Si docker version muestra Server, pero docker pull falla por DNS, proxy, TLS o autenticación, el CLI normalmente ya se conectó al motor. Revisa la red de Windows, el proxy de Docker Desktop, las credenciales del registro y su dirección, en vez de alternar la integración WSL.

Empieza con una comprobación de estado que no descargue una imagen y guarda el error completo. Si el problema solo aparece en la red de la empresa o con una VPN activa, compara DNS, la política del proxy y los requisitos de certificados corporativos bajo las mismas condiciones de red. No desactives el proxy de seguridad de la empresa ni omitas la validación de certificados para probar.

Un fallo de docker compose up también puede deberse a la configuración del proyecto o a la aplicación. Ejecuta docker compose config para revisar la configuración resultante y determina si falla la descarga, la creación del contenedor, el montaje del volumen o el inicio de la aplicación. Sigue la rama de integración WSL solo cuando el comando no puede conectarse al daemon.

Si el Engine conecta, pero las variables de Compose no llegan al contenedor, consulta la guía para solucionar variables de entorno de Docker Compose. Para problemas de disponibilidad de la base de datos y orden de inicio, consulta la guía de depends_on y healthcheck.

Espacio en disco, restablecimientos y límites de las copias de seguridad

Los datos del motor WSL 2 de Docker Desktop suelen estar en una ubicación de datos Docker WSL dentro del perfil del usuario, aunque los ajustes pueden cambiarla. Borrar ese disco virtual puede eliminar permanentemente imágenes, contenedores y datos de volúmenes locales. Clean up data y Reset to factory defaults tampoco son opciones de reinicio sin pérdida de datos.

Antes de limpiar, confirma que las bases de datos, imágenes o datos de contenedores que necesitas tengan copias de seguridad independientes. Que un contenedor se pueda reconstruir no significa que sus datos de volumen también. En entornos de empresa, revisa primero la política de retención y copias.

Prioriza el diagnóstico, el cierre normal y el reinicio de Docker Desktop. Borra datos o restablece los valores de fábrica solo después de entender el alcance y verificar la copia de seguridad.

Recopila diagnósticos y verifica la reparación

Si Docker Dashboard se abre, selecciona Get support en el menú Troubleshoot. Espera a que termine la recopilación, súbela y guarda el Diagnostic ID. Si la interfaz no arranca, utiliza el comando oficial docker desktop diagnose si está disponible; el soporte de línea de comandos depende de la versión de Docker Desktop.

Al informar del problema, incluye estos datos en vez de escribir solo «Docker no funciona»:

  • Versiones de Windows y Docker Desktop.
  • Salida de wsl --version, wsl --status y wsl -l -v.
  • Nombre de la distribución, versión de WSL y backend de Docker Desktop.
  • Salida completa de docker version tanto en PowerShell como en WSL.
  • Salida de docker context show y si están definidas DOCKER_HOST o DOCKER_CONTEXT.
  • Error completo, cuándo apareció, si hubo una actualización previa y el Diagnostic ID.

Después de corregirlo, verifica por separado en PowerShell y en la distribución WSL objetivo:

1
2
docker version
docker context show
1
2
3
command -v docker
docker version
docker context show

La integración solo queda verificada cuando ambos terminales se conectan al motor local esperado y docker version muestra Client y Server. Después ejecuta docker compose config y el comando de inicio del proyecto para confirmar montajes, red y variables de entorno.

Preguntas frecuentes

Docker funciona en Windows, pero Ubuntu no tiene el comando docker. ¿Debo reinstalarlo?

Activa primero el motor WSL 2 de Docker Desktop y la integración de Ubuntu; después cierra y vuelve a abrir WSL. No instales un segundo Docker Engine en Ubuntu como primer paso.

¿Qué significa que docker version solo muestre Client?

El CLI se ejecuta, pero no recibe respuesta de Engine Server. Comprueba el inicio de Docker Desktop, el context actual, DOCKER_HOST y el backend.

¿wsl --shutdown elimina contenedores?

Detiene todas las distribuciones WSL y la máquina virtual, pero no es un comando para borrar datos. Interrumpe el estado sin guardar de los procesos en ejecución. Inicia de nuevo Docker Desktop y la distribución objetivo para verificarlo.

¿Puedo borrar docker-desktop-data para solucionar el inicio?

No trates de borrar una distribución interna como reparación habitual. Podrías eliminar imágenes, contenedores o volúmenes locales. Recopila diagnósticos y revisa los pasos oficiales de recuperación; considera operaciones sobre datos solo después de confirmar la copia de seguridad.

¿Por qué docker funciona en WSL, pero fallan Dev Containers o Testcontainers?

Que funcione el comando no significa que estén disponibles todos los usos del socket Docker y de Engine API. Comprueba el backend de Docker Desktop; Docker VMM tiene limitaciones específicas de socket y montaje.

Referencias oficiales