Configurar WSL

Antes de usar WSL Dashboard, su sistema Windows debe tener el entorno WSL 2 correctamente habilitado y configurado. Este documento se divide en tres partes principales:

1. Habilitar y configurar WSL: instalación y configuración básica de WSL 2.
2. Que un comando esté disponible no significa que la instalación haya sido correcta: explica que poder ejecutar el comando wsl no significa que se pueda instalar Linux correctamente.
3. Solucionar errores de instalación: métodos de comprobación y reparación cuando la instalación sigue fallando tras la configuración.

1. Habilitar y configurar WSL

Este capítulo le guiará a través de la configuración básica necesaria. Tras completarlo, lea el capítulo 2 para entender la diferencia entre tener el comando disponible y haber instalado correctamente; si la instalación sigue presentando problemas, consulte el capítulo 3.

1.1 Comprobar los requisitos del sistema

WSL 2 tiene requisitos mínimos sobre la versión de Windows. Pulse Win + R e introduzca winver para comprobar su versión:

• Windows 10: versión 1903 o superior, con la compilación (Build) 18362 o superior.
• Windows 11: todas las versiones son compatibles.

IMPORTANT

Si su versión es demasiado antigua, actualice el sistema primero mediante "Windows Update".

1.2 Activar la virtualización de hardware

WSL 2 se ejecuta sobre tecnología de virtualización, por lo que debe habilitar la tecnología de virtualización (Virtualization Technology) en la BIOS/UEFI de la placa base.

• Método de comprobación: abra el "Administrador de tareas" -> pestaña "Rendimiento" -> "CPU".
• Comprobar el estado: confirme que el estado de "Virtualización" en la parte inferior derecha muestra "Habilitada".
• Cómo activarla: si no está habilitada, reinicie el equipo, entre en la configuración de BIOS/UEFI, busque una opción similar a Intel VT-x o AMD-V y establézcala en Enabled.

1.3 Habilitar las funciones de Windows relacionadas

Debe activar las funciones "Subsistema de Windows para Linux" y "Plataforma de máquina virtual" de Windows.

Método A: mediante la interfaz gráfica (recomendado)

1. Pulse Win + S, busque y abra "Activar o desactivar las características de Windows".
2. Marque las dos opciones siguientes:
   • Subsistema de Windows para Linux (Windows Subsystem for Linux)
   • Plataforma de máquina virtual (Virtual Machine Platform)
3. Haga clic en "Aceptar" y reinicie el equipo cuando se le indique.

Método B: mediante la línea de comandos (privilegios de administrador)

Ejecute PowerShell como administrador y ejecute los siguientes comandos:

# Habilitar WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Habilitar la plataforma de máquina virtual
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Tras la ejecución, reinicie el equipo manualmente.

1.4 Instalar/actualizar el kernel de WSL

Las versiones modernas de Windows pueden obtener las actualizaciones de WSL a través de Microsoft Store.

• Dirección de descarga: Microsoft Store - Windows Subsystem for Linux
• Descarga manual: si no puede usar la tienda, descargue el paquete .msixbundle o .msi más reciente desde WSL GitHub Releases para instalarlo sin conexión.

1.5 Establecer WSL 2 como versión predeterminada

Para garantizar que las nuevas distribuciones instaladas usen WSL 2 de forma predeterminada, ejecute en el terminal:

wsl --set-default-version 2

1.6 Preguntas frecuentes

• Error 0x80370102: suele deberse a que la virtualización no está habilitada en la BIOS o a un conflicto con Hyper-V.
• Cambio entre WSL 1 y WSL 2: puede usar wsl --set-version <nombre-de-la-distribución> 2 para actualizar una instancia existente de WSL 1 a WSL 2.

2. Que un comando esté disponible no significa que la instalación haya sido correcta

Que comandos como wsl --version o wsl -l -v se ejecuten correctamente no significa que ya esté en condiciones de instalar Linux. Son fases distintas y no deben equipararse.

Que los comandos estén disponibles solo indica:

• ✅ Los componentes de WSL de Windows ya están habilitados/instalados
• ✅ La herramienta de línea de comandos wsl.exe está disponible
• ✅ El sistema reconoce los comandos relacionados con WSL

Pero instalar correctamente una distribución de Linux requiere condiciones adicionales. Los puntos donde suele quedarse atascada la gente son:

1. Virtualización desactivada: VT-x / AMD-V no está habilitado en la BIOS/UEFI, por lo que WSL 2 no puede arrancar, o al instalar la distribución se reporta un error de virtualización (método de comprobación en 1.2 Activar la virtualización de hardware).
2. Versión/compilación de Windows demasiado antigua: WSL 2 tiene requisitos de kernel y versión; la edición Home o las imágenes empresariales demasiado antiguas pueden carecer de funciones (método de comprobación en 1.1 Comprobar los requisitos del sistema).
3. Aún no se ha instalado realmente una distribución de Linux: wsl -l -v solo lista las distribuciones instaladas; si no hay ninguna instalada, la lista estará vacía, lo que no significa que se pueda ejecutar Ubuntu directamente.
4. Problemas de red / Microsoft Store: wsl --install -d <distribución> necesita descargar la imagen desde la tienda o la red; las redes corporativas, los proxies y los firewalls pueden bloquearla.
5. Permisos insuficientes: instalar distribuciones o modificar los ajustes de WSL requiere permisos de administrador.

TIP

En resumen: que los comandos WSL funcionen ≠ Linux listo; solo ha obtenido la "entrada", pero todavía no ha instalado el sistema.

3. Solucionar errores de instalación

Tras completar la configuración siguiendo el capítulo 1 (o si cree que ya la ha completado), si wsl --install sigue fallando, compruebe lo siguiente en orden.

3.1 Primero, haga la "comprobación en un clic"

Ejecute PowerShell como administrador y ejecute sucesivamente:

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ Si ambos comandos se ejecutan sin problemas, significa que los componentes opcionales de WSL están habilitados y que la virtualización cumple los requisitos básicos.
• ❌ Si fallan, se indicará directamente qué falta (p. ej., plataforma de máquina virtual, Hyper-V, virtualización en BIOS, etc.).

Ejecute después systeminfo y confirme que en la salida aparece Virtualization Enabled In Firmware: Yes. Si no hay ningún error en lo anterior, ya puede ejecutar wsl --install para instalar la distribución con tranquilidad.

NOTE

Ningún comando puede garantizar al 100 % que wsl --install tendrá éxito, pero las comprobaciones anteriores confirman si se cumplen las condiciones de instalación.

3.2 Lista de comprobación manual

Si la "comprobación en un clic" no logra localizar el problema, puede revisar punto por punto:

1. Comprobar si la virtualización de BIOS/firmware está activada: en PowerShell de administrador ejecute systeminfo; en la salida debe aparecer Virtualization Enabled In Firmware: Yes.
2. Comprobar si las funciones de Windows están habilitadas:

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   El estado de ambos comandos debe ser Enabled.
3. Comprobar si WSL está disponible: wsl --version debe producir una salida normal; si indica que el comando no existe, significa que los componentes de WSL no están instalados; vuelva al capítulo 1.
4. Comprobar si se puede usar WSL 2 (kernel y plataforma de máquina virtual): wsl --set-default-version 2 debe devolver correctamente. Causas habituales de error: la plataforma de máquina virtual no está habilitada o VT-x / AMD-V no está activado en la BIOS.

3.3 Referencia rápida de causas de error frecuentes

Situación	Descripción	Solución
Virtualización desactivada en la BIOS	Fallo garantizado	Reinicie, entre en la BIOS y active VT-x / AMD-V (ver 1.2)
Windows 10 inferior a 19041	wsl --install no compatible	Actualice el sistema (ver 1.1)
Entorno empresarial con Hyper-V/virtualización deshabilitada	Puede fallar	Contacte con el administrador del sistema
Edición Home antigua	Requiere instalación manual	Instale el kernel de WSL manualmente según 1.4

3.4 Error 0xc03a0014: no se encuentra el proveedor de soporte del disco virtual

El mensaje de error es Cannot find a virtual disk support provider for the specified file. No es un problema de la distribución de Linux en sí, sino que la pila de discos virtuales VHD/VHDX de Windows no funciona correctamente; WSL 2 falla al registrar la distribución o al crear/montar ext4.vhdx.

Haga primero una verificación mínima: ejecute PowerShell como administrador y pruebe New-VHD (por ejemplo, New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Si este comando también reporta el mismo error, el problema está 100 % en el lado de Windows, no en la distribución.

Siga este orden para diagnosticar y reparar:

1. El servicio Virtual Disk no está en ejecución: abra services.msc, busque el servicio Virtual Disk, establezca el tipo de inicio en "Automático" e inícielo.

2. Las funciones WSL / Plataforma de máquina virtual no están habilitadas (o no surtieron efecto): vuelva a ejecutar los comandos de 1.3 Habilitar las funciones de Windows relacionadas y luego debe reiniciar. La edición Home de Windows no tiene Hyper-V completo, pero WSL 2 solo necesita la plataforma de máquina virtual, no la consola de administración de Hyper-V.

3. Faltan controladores/dispositivos de disco virtual: abra el Administrador de dispositivos y compruebe si existen los siguientes en "Dispositivos del sistema / Controladores de almacenamiento":

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   Si faltan, puede agregarlos manualmente con hdwwiz.exe (Controladores de almacenamiento → Microsoft → Microsoft VHD Loopback Controller) y confirme que el servicio FsDepends no está deshabilitado.

4. La imagen importada no cumple los requisitos de WSL: al usar wsl --import --vhd, el VHDX debe ser un sistema de archivos ext4; no puede ser un disco cifrado con LUKS, un raw.img normal, un Live ISO ni un disco vacío formateado en NTFS/FAT. .img / .qcow2 / .iso no se pueden usar directamente con wsl --import --vhd.

5. Problemas de ruta/permisos/sistema de archivos: el directorio de destino debe estar en un disco NTFS (FAT32/exFAT no sirven); evite caracteres chinos, espacios y símbolos especiales en la ruta; no importe desde unidades de red, OneDrive o carpetas comprimidas; use siempre PowerShell de administrador real (no un terminal normal).

6. Componentes del sistema dañados: ejecute DISM y SFC sucesivamente para reparar los componentes del sistema y vuelva a intentarlo:

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

Las máquinas virtuales de terceros (VirtualBox, VMware) o las funciones de sandbox/endurecimiento de programas de seguridad (como 360, Huorong) pueden interferir con las operaciones de discos virtuales; durante la comprobación puede desactivarlas temporalmente y volver a probar.