Guía completa para crear entornos con WSL2 + Docker + VS Code

Si trabajas en Windows y quieres un entorno de desarrollo sólido con Linux, contenedores y editor moderno, WSL2, Docker y VS Code forman un trío ganador. Este combo permite programar en Linux sin abandonar Windows, ejecutar contenedores de forma ágil y depurar proyectos con comodidad, todo en la misma máquina.

La idea es sencilla: aprovechar el kernel Linux de WSL2, añadir Docker (ya sea mediante Docker Desktop o instalando el motor nativo en la distro) y rematar con VS Code y Dev Containers para obtener entornos reproducibles. En las siguientes secciones verás paso a paso cómo montarlo, con recomendaciones prácticas, atajos, casos reales y soluciones a problemas típicos.

Contenedores y por qué encajan con WSL2 + VS Code

Docker permite empaquetar aplicaciones con todo lo necesario para que se ejecuten igual en cualquier máquina. Frente a una VM tradicional, los contenedores comparten el kernel del host, arrancan más rápido y consumen menos. Además, facilitan la disponibilidad continua: subes una nueva versión del contenedor y sustituyes sin parar el sistema entero.

Con WSL2, Windows trae un kernel Linux real integrado. Gracias a ello, los contenedores Linux funcionan de forma nativa en tu equipo, y si usas Docker Desktop con backend WSL 2 puedes ejecutar contenedores Linux y Windows lado a lado. Esto combina rendimiento, compatibilidad y flujo de trabajo unificado.

Requisitos y preparación del sistema

Antes de nada, conviene verificar que Windows cumple con los requisitos para WSL2 y Docker Desktop. Revisa las versiones y build de Windows (Win + R, escribe «winver») y ten presente que Docker Desktop tiene requisitos de sistema y licencia específicos (gratuito para uso personal y pequeñas empresas).

Para instalar WSL2 con el método simplificado, abre PowerShell o CMD con permisos y ejecuta wsl --install. Este comando habilita los componentes necesarios, instala el kernel Linux, establece WSL 2 como predeterminado y descarga Ubuntu por defecto. Reinicia cuando lo pida.

Tras la instalación, abre la distro (Ubuntu si no has cambiado) y crea tu usuario y contraseña de Linux. Recuerda que mientras escribes la contraseña no verás caracteres: es normal. Esta cuenta será la predeterminada y podrá ejecutar sudo para tareas administrativas.

Mantén la distro al día con sudo apt update && sudo apt upgrade. Windows no actualiza automáticamente la distribución, así que tú decides cuándo. Si quieres añadir más distros, puedes hacerlo desde Microsoft Store o importando imágenes.

Terminal, almacenamiento y editor: primeras decisiones

Instala Windows Terminal para una experiencia moderna con pestañas, paneles y temas. Gestiona varias líneas de comandos sin dolor y personaliza a tu gusto. Cada vez que sumes una distro de WSL, aparecerá su perfil correspondiente en el terminal.

En cuanto a los archivos del proyecto, es clave el rendimiento: si usas herramientas Linux, guarda los proyectos en el sistema de archivos de WSL2 (por ejemplo, \\wsl$\Ubuntu-22.04\home\tuusuario\proyecto). Se puede acceder desde ambos lados, pero trabajar en /mnt/c con herramientas Linux puede ser más lento.

Para abrir la carpeta actual de WSL en el Explorador, ejecuta explorer.exe . (incluye el punto). Y para abrir la carpeta en VS Code desde WSL, utiliza code .. Con la extensión correcta, VS Code se conecta al servidor de extensiones dentro de WSL y te olvidas de rutas extrañas y problemas de binarios.

Instalar Docker Desktop con backend WSL 2

Una ruta muy cómoda es usar Docker Desktop. Descárgalo, instálalo y activa «Use the WSL 2 based engine» en Configuración > General. Después, en Configuración > Resources > WSL Integration, elige las distros WSL2 donde quieres habilitar la integración.

Verifica la instalación desde tu distro con docker --version y prueba con docker run hello-world. Si todo está bien, tendrás contenedores Linux corriendo sobre el kernel de WSL2 y gestionados por Docker Desktop en Windows.

Docker Desktop crea dos distribuciones especiales de WSL para almacenamiento y servicio: docker-desktop y docker-desktop-data. También verás sus rutas como \\wsl$\docker-desktop y \\wsl$\docker-desktop-data. Si necesitas localizar sus datos desde Windows, puedes abrir una shell WSL y ejecutar explorer.exe ., o navegar a \\wsl\<Distro>\mnt\wsl.

Si vienes de una vista previa antigua de Docker para WSL, puede que quede un contexto en desuso llamado «wsl». Compruébalo con docker context ls; si aparece, elimínalo con docker context rm wsl para evitar errores como «open \\.\/pipe\/docker_wsl». En la integración actual debes usar el contexto por defecto.

Desarrollar en contenedores remotos con VS Code

Para trabajar de forma cómoda con contenedores, instala en VS Code las extensiones WSL, Dev Containers y Docker. Con ellas, podrás abrir tu proyecto WSL en VS Code, y además reabrir la carpeta dentro de un contenedor de desarrollo con todo el stack listo.

Ejemplo práctico (Django). Desde tu terminal WSL clona un repositorio, como el de un “Hello World” de Django: git clone https://github.com/mattwojo/helloworld-django.git, entra con cd helloworld-django y abre VS Code con code .. Comprueba el indicador verde de conexión remota a WSL en la esquina inferior izquierda.

Abre la paleta (Ctrl + Shift + P) y elige “Dev Containers: Reopen in Container” (o “Open Folder in Container…” si vienes desde Windows mediante \\wsl$). Selecciona una definición adecuada (por ejemplo, Python 3 para Django). VS Code generará una carpeta .devcontainer con Dockerfile y devcontainer.json, construirá la imagen y levantará el contenedor de desarrollo.

Abre el terminal integrado y ejecuta uname para confirmar que estás en Linux, y python3 --version para ver la versión de Python del contenedor. Para depurar, ve a la vista Ejecutar y Depurar, crea el launch.json eligiendo la configuración del framework (Django en este caso) y pulsa F5. Abre la URL que te indique el terminal (por ejemplo, http://127.0.0.1:8000).

Dev Containers y Codespaces: entornos reproducibles

Un Dev Container se define con .devcontainer/devcontainer.json y, opcionalmente, un Dockerfile. Este enfoque permite usar imágenes base u otras personalizadas, preinstalar dependencias, configurar extensiones de VS Code y automatizar comandos post-configuración.

Entre los casos de uso más comunes están los de Data Science colaborativo (con Python, Jupyter, pandas, seaborn y un conjunto homogéneo de dependencias) y los de backend Node.js con PostgreSQL coordinados con docker-compose.yml. De esta manera, todo el equipo trabaja con el mismo entorno, sin sorpresas por diferencias locales.

La misma carpeta .devcontainer funciona en la nube con GitHub Codespaces: al crear un Codespace, GitHub construye automáticamente el entorno. Esto favorece el cambio sin fricción entre local y nube, reproducibilidad e incorporación rápida de nuevos colaboradores.

Buenas prácticas: considera las imágenes base oficiales devcontainers/, versiona la carpeta .devcontainer, usa postCreateCommand para automatizar instalaciones y combina devcontainer.json con docker-compose.yml cuando necesites varios servicios.

Alternativa: Docker sin Docker Desktop (motor nativo en WSL2)

Si prefieres evitar Docker Desktop (por política de empresa o elección personal), puedes instalar el motor de Docker directamente en tu distro WSL2. Añade la clave GPG, el repositorio oficial y los paquetes (en Ubuntu):

Sigue estos comandos para añadir la clave y el repositorio: # Clave oficial y repositorio
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo «deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https:\/\/download.docker.com\/linux\/ubuntu \n$(. \/etc\/os-release && echo «$VERSION_CODENAME») stable» |
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Añade tu usuario al grupo docker para usar el CLI sin sudo: sudo usermod -aG docker $USER. Cierra y reabre WSL. Comprueba con docker run hello-world. Para autoarranque puedes usar /etc/wsl.conf con [boot] y command = service docker start, o systemd si ya está habilitado en tu WSL2 (en versiones recientes).

Red y puertos: desde Windows podrás acceder a contenedores publicados en localhost gracias a WSL2. Si necesitas exponer servicios de WSL2 hacia tu red local (por ejemplo, acceder desde el móvil), usa un port proxy en Windows con netsh y crea la regla de firewall correspondiente. Un script de PowerShell típico obtiene la IP de WSL, configura portproxy y añade la regla; así evitas repetir comandos tras reinicios.

¿Por qué elegir esta ruta? Evitas depender de licencias o políticas de Docker Desktop y controlas cada pieza. Como complemento, puedes desplegar Portainer para gestionar contenedores con interfaz web: crea un volumen y levanta el contenedor con los puertos 8000 y 9443; accede a https://localhost:9443 (acepta el certificado), crea el usuario admin y gestiona tu Docker con clics.

Git, SSH y dónde clonar el código

En WSL2 puedes clonar con Git en tu directorio home de Linux y trabajar con VS Code. Esta suele ser la opción más cómoda: mejor rendimiento y menos fricción. Si prefieres clonar desde un contenedor, tendrás que gestionar las credenciales y claves SSH dentro del contenedor o montar tu ~/.ssh con cuidado.

¿GUI para Git? Herramientas como Sublime Merge o GitKraken pueden funcionar en este escenario. GitKraken incluso puede abrirse desde la terminal de WSL y mostrarse en Windows, teniendo acceso a los archivos de WSL. Para SSH con GitLab u otros remotos, configura tus claves en WSL y comprueba permisos y agentes SSH antes de clonar por SSH.

Recuerda el consejo de rendimiento: evita /mnt/c para tu código si vas a compilar o usar herramientas Linux intensivas. Usa \\wsl$ desde Windows para acceder a la misma carpeta cuando lo necesites.

Productividad en la terminal: ZSH, Oh My Zsh, Powerlevel10k, Antigen, FZF y Tmux

Para una terminal cómoda y potente, instala ZSH con sudo apt install zsh y cámbiala por defecto con chsh -s $(which zsh). Después instala Oh My Zsh con su script oficial y dale un aspecto y funcionalidad avanzados.

El tema Powerlevel10k añade un prompt muy configurable con integración Git y rendimiento excelente. Instálalo desde su repo, coloca ZSH_THEME="powerlevel10k/powerlevel10k" en ~/.zshrc y sigue el asistente para ajustar fuentes y aspecto. Verás tu estado de repo, rama y más de un vistazo.

Con Antigen gestionarás plugins de ZSH de forma declarativa. Paquetes útiles: zsh-autosuggestions, un plugin para fzf, soporte zsh-npm-scripts-autocomplete y zsh-z para saltar entre directorios. Añade NVM como plugin u oficialmente para cambiar de versión de Node en caliente.

Mejora el flujo con bat y fd desde apt (bat y fd-find en Ubuntu), y configura fzf para búsquedas: Ctrl + R para historial, Alt + C para carpetas y Ctrl + T para archivos con previsualización en color. Ganancias de tiempo inmediatas en el día a día.

Para multiplexar la terminal, usa Tmux (sudo apt install tmux) y su gestor de plugins TPM. Con una configuración adecuada tendrás temas, recuperación de sesiones (resurrect/continuum), integración con navegación tipo Vim y atajos para dividir paneles. Instala plugins con Ctrl + Espacio y luego I (i mayúscula) dentro de Tmux.

Bases de datos, GPU y aplicaciones gráficas

Tu proyecto puede necesitar una base de datos. Tienes guías para MySQL, PostgreSQL, MongoDB, Redis, SQL Server o SQLite corriendo dentro de WSL o como contenedores. Integra servicios en docker-compose.yml y haz que tu Dev Container se conecte a ellos sin complicaciones.

¿Aceleración por GPU? WSL2 ofrece soporte para workloads de machine learning usando la GPU, con especial foco en NVIDIA y CUDA. En tarjetas AMD/Intel hay caminos alternativos; revisa la documentación de tu fabricante para habilitar la aceleración.

WSL2 permite ejecutar aplicaciones de GUI de Linux en Windows. Para casos puntuales, puedes abrir editores o herramientas gráficas de Linux y se mostrarán en ventanas de Windows. Si ves glitches, reiniciar WSL2 con wsl --shutdown suele arreglarlo.

Interoperabilidad y comandos útiles

WSL y Windows se entienden bien. Desde PowerShell, ejecuta comandos Linux con wsl, por ejemplo: wsl ls -la. También puedes mezclar: wsl ls -la | findstr "git" o dir | wsl grep git para filtrar entre mundos.

Desde Linux ejecuta herramientas de Windows añadiendo .exe: notepad.exe .bashrc. También combinaciones útiles: ipconfig.exe | wsl grep IPv4 | wsl cut -d: -f2 para quedarte con la IP. Todo fluye entre ambos sistemas.

Para montar unidades externas en WSL2, sigue la guía de montaje de discos. Podrás acceder a USB o discos adicionales y trabajar con ellos desde Linux.

Red, puertos y localhost

WSL2 mapea automáticamente los puertos del entorno Linux a localhost en Windows. Es decir, si publicas un -p 3000:3000 en Docker, podrás entrar a http://localhost:3000 desde tu navegador en Windows sin hacer nada más.

Si quieres exponer servicios de WSL2 a la LAN (otro dispositivo en tu red), puedes usar un script de PowerShell que obtenga la IP de WSL e invoque netsh interface portproxy para forwardear puertos, además de crear la regla de firewall con New-NetFirewallRule. Esto automatiza la publicación y evita repetir manualmente los pasos tras reinicios.

Problemas frecuentes y cómo resolverlos

Contextos obsoletos de Docker en WSL: si te aparece uno llamado “wsl” heredado de previews antiguas, bórralo con docker context rm wsl. Así evitarás errores como open \\.\/pipe\/docker_wsl y te quedarás con el contexto por defecto.

¿Dónde guarda Docker sus datos bajo WSL? Busca \\wsl$\docker-desktop y \\wsl$\docker-desktop-data, o abre tu distro y lanza explorer.exe . para navegar. También tienes \\wsl\<Distro>\mnt\wsl para ver almacenamiento relacionado.

Glitches de ventanas GUI lanzadas desde WSL: a veces las apps basadas en Electron muestran artefactos. Reinicia WSL2 con wsl --shutdown y vuelve a intentarlo. Microsoft va corrigiendo estos detalles con el tiempo.

¿Sin systemd? En iteraciones recientes WSL2 puede activar systemd por defecto; si no es tu caso, puedes iniciar servicios con /etc/wsl.conf y la sección [boot]. Comprueba tu versión y documentación si necesitas servicios en background.

Actualizaste de WSL1 a WSL2 y Docker no coopera: a veces quedan restos de configuraciones antiguas como DOCKER_HOST=tcp://localhost:2375. Si vienes de esa configuración, desinstala Docker por completo en Windows y WSL (paquetes, rutas y ficheros de configuración), y reinstala Docker Desktop con backend WSL 2. Verifica con wsl -l -v que existen docker-desktop y docker-desktop-data en versión 2.

Si usas el motor nativo en WSL2 sin Desktop y expones el demonio por TCP, recuerda que sin TLS es inseguro. Esta configuración es para entornos de desarrollo locales, no producción. Asegúrate de controlar bien tu red y evita puertos abiertos innecesarios.

Consejos finales y buenas prácticas

En proyectos con docker-compose.yml que asumen automatizaciones de Docker Desktop (montajes y alias de red), ajusta rutas absolutas si ves volúmenes con ~ y añade extra_hosts con host.docker.internal:host-gateway si tu stack lo requiere. Pequeños cambios evitan sorpresas.

Para VS Code, el combo WSL + Dev Containers + Docker te permite trabajar dentro del contenedor con las mismas extensiones y configuración del editor. Es una forma de estandarizar el entorno entre miembros del equipo y reducir “en mi máquina funciona”.

Si prefieres un enfoque sin Docker Desktop, el motor nativo en WSL2 ofrece control granular y, con Portainer, una interfaz de gestión ligera. Ambas rutas son válidas y dependerán de tus necesidades, licencias y políticas internas.

Dispones de un mapa completo: instalar y configurar WSL2, elegir entre Docker Desktop o motor nativo, trabajar con Dev Containers y VS Code, usar bases de datos y GPU, y elevar tu productividad con una terminal afinada y Tmux. La clave es combinar estas piezas según tu proyecto y equipo para lograr un entorno reproducible, rápido y cómodo en el día a día.