Integración de WSL2 con Docker en Windows: guía práctica y completa

Si trabajas en Windows y quieres desarrollar como si estuvieras en Linux, la pareja formada por WSL 2 y Docker es de lo mejorcito que puedes montar en tu equipo. Con esta integración conseguirás contenedores de Linux y Windows en la misma máquina, menos consumo de recursos y un arranque del demonio muchísimo más rápido que con otras opciones más pesadas.

En las próximas líneas encontrarás una guía completa para poner a punto Docker Desktop con backend WSL 2, o si lo prefieres, ejecutar Docker directamente dentro de WSL 2 sin depender de Docker Desktop. Además, verás cómo sacarle partido con Visual Studio Code, consejos de rendimiento, rutas de almacenamiento, y una sección de solución de problemas con errores típicos y su remedio.

Contenedores y WSL 2: lo que necesitas saber

Docker empaqueta aplicaciones con sus dependencias dentro de contenedores para que se ejecuten igual en cualquier entorno. A diferencia de una VM clásica, un contenedor no necesita un sistema operativo completo: comparte el kernel del host y sólo añade lo que tu app no tiene ya disponible, reduciendo tamaño y acelerando la ejecución.

Frente a una máquina virtual, este enfoque ahorra memoria y CPU porque no levanta un SO entero. En Windows, WSL 2 aporta un kernel Linux real con compatibilidad de llamadas al sistema, por lo que Docker puede funcionar de manera nativa con un rendimiento muy sólido.

Otra ventaja clave es la disponibilidad continua. Gracias a los contenedores y orquestadores como Kubernetes, puedes actualizar servicios por versiones, sustituir contenedores en caliente y mantener varias revisiones como respaldo sin tirar abajo el sistema completo.

En resumen, Docker favorece entornos consistentes, minimiza conflictos de dependencias y acelera despliegues. Unido a WSL 2 en Windows, obtienes un flujo de trabajo Linux sin salir de tu escritorio, con integración de archivos y puertos expuestos a localhost de forma automática.

Requisitos previos en Windows

Comprueba que tu Windows 10/11 cumple las condiciones mínimas: 64 bits, virtualización activada en la BIOS/UEFI y al menos 4 GB de RAM. En builds modernas basta con habilitar WSL y su plataforma de virtualización.

Para activar los componentes desde PowerShell como administrador, puedes usar comandos del estilo de habilitar WSL y la Plataforma de Máquina Virtual. En equipos actualizados, el proceso se simplifica con WSL:

wsl --install

Si ya tenías WSL, establece WSL 2 por defecto y verifica o migra tus distribuciones instaladas:

wsl --set-default-version 2
wsl -l -v
wsl --set-version Ubuntu 2

Para elegir la distro predeterminada con la que te integrarás, puedes cambiar el valor por defecto cuando lo necesites:

wsl -s Ubuntu

Instalar Docker Desktop con motor basado en WSL 2

La ruta más directa para un entorno pulido es usar Docker Desktop con backend WSL 2. Descarga el instalador de Docker Desktop para Windows, ejecútalo y sigue el asistente. Si tu sistema es compatible, el uso del motor WSL 2 aparecerá marcado o se te sugerirá activarlo durante la instalación.

Tras iniciar Docker Desktop, abre su panel de Settings y, en la sección General, activa la opción de motor basado en WSL 2 si no lo está ya. Con eso, podrás ejecutar contenedores de Linux desde Windows sin Hyper-V tradicional.

Después, entra en Settings > Resources > WSL Integration y habilita la integración para la(s) distribución(es) de WSL 2 que vayas a utilizar (por ejemplo, Ubuntu). Si la pestaña de integración WSL no aparece, verifica que estás en modo Linux containers y no en Windows containers.

Para validar que todo está en su sitio, abre tu distro WSL (por ejemplo Ubuntu) y ejecuta los comandos de verificación:

docker --version
docker run hello-world

Con esto confirmas que el binario CLI y el daemon responden. Si puedes tirar la imagen de prueba hello-world, la integración está funcionando.

Desarrollar en contenedores con Visual Studio Code

Con WSL 2 y Docker operativos, la experiencia de desarrollo se potencia mucho con Visual Studio Code y tres extensiones oficiales: WSL, Dev Containers y Docker. Cada una aporta una pieza del puzzle para trabajar desde Windows dentro de Linux con contenedores.

Instala la extensión WSL para abrir carpetas de tu distro directamente en VS Code. Así no batallarás con rutas, binarios incompatibles o líos de permisos entre sistemas.

Instala Dev Containers para abrir la carpeta del proyecto en un contenedor y desarrollar con el entorno definido en un Dockerfile y un devcontainer.json. Es una manera cómoda de estandarizar herramientas y dependencias del equipo.

Instala también la extensión Docker para compilar, ejecutar y administrar imágenes, contenedores y volúmenes desde el propio sidebar de VS Code. Facilita bastante el día a día sin salir del editor.

Un flujo típico sería: clonar el proyecto en WSL, abrirlo con code ., y lanzar en la paleta de comandos la acción Dev Containers para Reabrir en contenedor. VS Code generará una carpeta .devcontainer con su Dockerfile y devcontainer.json apropiados a tu stack (por ejemplo, Python/Django) y construirá la imagen.

Comprueba que sigues en Linux ejecutando en el terminal integrado de VS Code: uname y python3 --version. Verás Linux (WSL 2) y la versión de Python definida por el contenedor, que puede diferir de la que tengas en la distro. Con la configuración de Run and Debug (por ejemplo, perfil Django), podrás ejecutar y depurar tu aplicación en el contenedor, accediendo a la URL local que te indique, normalmente http://127.0.0.1:8000/.

Ejecutar Docker sin Docker Desktop: instalación directa en WSL 2

Si por licenciamiento o preferencias quieres evitar Docker Desktop, puedes instalar Docker Engine dentro de tu distro WSL 2. En Ubuntu, actualiza paquetes, añade el repo oficial y procede con la instalación de los componentes necesarios:

sudo apt update && sudo apt upgrade

source /etc/os-release
curl -fsSL https://download.docker.com/linux/${ID}/gpg | sudo apt-key add -
echo "deb [arch=amd64] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

Para no tener que anteponer sudo a cada comando, añade tu usuario al grupo docker y vuelve a iniciar la sesión de la distro:

sudo usermod -aG docker $USER

Arranca el demonio cuando lo necesites dentro de WSL 2 con:

sudo dockerd

Si ves un mensaje del estilo API listen on /var/run/docker.sock, el servidor está en marcha. Abre otra terminal de la distro y prueba que todo responde con:

docker run --rm hello-world

Usar la CLI de Docker desde Windows con Docker en WSL 2

Para invocar docker y docker-compose desde el lado Windows mientras el daemon vive en WSL 2, descarga docker.exe y docker-compose.exe y añádelos al PATH de tu usuario de Windows. Así podrás lanzar comandos desde PowerShell o VS Code en terminales de Windows.

Puedes crear un script de PowerShell que obtenga la IP de la distro WSL 2 y arranque el daemon escuchando por TCP, estableciendo la variable de entorno DOCKER_HOST en Windows. Un ejemplo de flujo podría ser:

$ip = (wsl sh -c "hostname -I").Split(" ")[0]
$DOCKER_HOST = "tcp://" + $ip + ":2375"
[System.Environment]::SetEnvironmentVariable('DOCKER_HOST',$DOCKER_HOST,[System.EnvironmentVariableTarget]::User)
wsl sh -c "sudo dockerd --tls=false -H tcp://$ip"

Verás advertencias indicando que abrir el daemon sin TLS es inseguro. Esta configuración es exclusivamente para desarrollo local; no la uses en producción. En otra ventana de PowerShell puedes probar:

docker version
docker container ls
docker run --rm hello-world
docker run -it --rm -p 8080:80 uzyexe/tetris

Si necesitas orquestar varios servicios, docker-compose seguirá funcionando. Por ejemplo, con un fichero de ejemplo podrías levantar una app con base de datos y verificar el mapeo de puertos accediendo a localhost en el puerto que hayas expuesto.

Ajustes habituales en docker-compose sin Docker Desktop

Cuando trabajas sin Docker Desktop, hay automatismos que ya no están, por lo que conviene ajustar dos cosas en tus docker-compose.yml:

• En volúmenes que usen la tilde de home ~, reemplázala por la ruta real de tu home en WSL 2, por ejemplo /mnt/c/Users/tu-usuario si apuntas a archivos en C: desde la distro.
• Añade la sección extra_hosts cuando tu proyecto dependa del alias host.docker.internal:

extra_hosts:
- host.docker.internal:host-gateway

Con ello te evitas sorpresas de conectividad entre contenedores y el host, replicando facilidades que Docker Desktop ofrece de serie.

Rendimiento y buenas prácticas con WSL 2

Docker Desktop sobre WSL 2 usa asignación dinámica de memoria, consumiendo lo justo y acelerando operaciones intensivas como builds. Además, el arranque en frío del daemon es sensiblemente más veloz que con alternativas basadas en VMs convencionales.

La recomendación de oro: mantén los archivos de tus proyectos dentro del sistema de archivos de WSL 2. Trabajar desde /home/tu-usuario en la distro evita las penalizaciones de I/O que aparecen al montar rutas de Windows bajo /mnt/c para tareas con mucho acceso a disco.

En Docker Desktop, asegúrate de tener activo Use WSL 2 based engine y de habilitar la integración de la distro correcta en Settings > Resources > WSL Integration. Si haces esto y te mueves los proyectos a la ruta adecuada, la diferencia en fluidez se nota muchísimo.

Si necesitas más aislamiento por políticas corporativas, valora usar el modo Hyper-V en Docker Desktop o habilitar Enhanced Container Isolation. Para la mayoría de escenarios de desarrollo, WSL 2 ofrece un equilibrio excelente entre rendimiento y simplicidad.

Carpetas de almacenamiento y accesos útiles

Docker Desktop crea dos distribuciones WSL internas para sus datos: docker-desktop y docker-desktop-data. Puedes acceder a sus carpetas desde Windows con rutas UNC si lo necesitas para inspeccionar contenido.

Un truco cómodo: desde tu distro WSL lanza explorer.exe . para abrir el directorio actual en el Explorador de archivos. También puedes navegar directamente a los puntos de montaje persistentes con:

\\wsl$\<Distro>\mnt\wsl

Reemplaza <Distro> por el nombre de tu distribución, como Ubuntu-24.04, para encontrar las ubicaciones internas donde WSL expone sus volúmenes y donde Docker Desktop guarda datos cuando trabaja sobre WSL 2.

Solución de problemas frecuentes

Si vienes de versiones previas de la integración, quizá conserves un contexto de Docker antiguo llamado wsl que ya no se usa. Comprueba tus contextos y bórralo para evitar errores:

docker context ls
docker context rm wsl

Este contexto obsoleto puede provocar mensajes del estilo de error al abrir pipes de docker_wsl en Windows. Eliminarlo devuelve a la configuración predeterminada que funciona tanto desde Windows como desde WSL 2.

Si no ves la sección WSL Integration en Docker Desktop, puede que estés en modo Windows containers. Cambia a Linux containers desde el icono de la bandeja del sistema. Después vuelve a Settings para habilitar la integración.

Recuerda que WSL expone el sistema de archivos al host en \\wsl$\. Esto no es algo exclusivo de Docker Desktop, sino parte del modelo de interoperabilidad de WSL. Docker Desktop, por su parte, corre en su distro interna docker-desktop, con el mismo aislamiento que cualquier otra distribución WSL; sólo interactúa con otras cuando activas la integración WSL.

Si buscas endurecer el entorno por motivos de seguridad, plantéate usar Hyper-V o políticas avanzadas de aislamiento de contenedores. Para desarrollo general, WSL 2 es suficiente, pero hay organizaciones que prefieren un cerco extra según su nivel de riesgo.

Con todo lo anterior ya tienes una foto completa para elegir cómo trabajar: usar Docker Desktop con motor WSL 2 para una experiencia guiada y estable, o instalar Docker directamente en WSL 2 para reducir dependencias externas; si además combinas VS Code, sus extensiones y alojas los proyectos dentro del sistema de archivos de WSL, disfrutarás de un entorno ágil y coherente, con controles finos de rendimiento, rutas claras de datos y soluciones inmediatas a los errores habituales.