Habilitar y configurar WSL

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

1. Habilitar y configurar WSL: completar la instalación y configuración básica de WSL 2.
2. Que el comando esté disponible no significa que la instalación haya sido exitosa: explica que poder ejecutar el comando wsl no significa que Linux pueda instalarse correctamente.
3. Solución de problemas de instalación: métodos de verificación y reparación cuando la instalación sigue fallando después de la configuración.

1. Habilitar y configurar WSL

Este capítulo le guiará para completar la configuración básica necesaria. Después de completar este capítulo, lea el capítulo 2 para comprender la diferencia entre la disponibilidad del comando y el éxito de la instalación; si la instalación aún presenta problemas, consulte el capítulo 3.

1.1 Verificar los requisitos del sistema

WSL 2 tiene requisitos mínimos de versión de Windows. Presione Win + R, ingrese winver para verificar su versión:

• Windows 10: versión 1903 o superior, y el número de compilación (Build) debe ser 18362 o superior.
• Windows 11: todas las versiones son compatibles.

IMPORTANT

Si su versión es demasiado antigua, primero actualice su sistema a través de "Windows Update".

1.2 Habilitar la virtualización de hardware

WSL 2 funciona basado en tecnología de virtualización, por lo que debe habilitar Virtualization Technology en la BIOS/UEFI de la placa base.

• Método de verificación: abra el "Administrador de tareas" -> pestaña "Rendimiento" -> "CPU".
• Ver el estado: confirme que el estado de "Virtualización" en la esquina inferior derecha muestre "Habilitado".
• Forma de habilitar: si no está habilitada, debe reiniciar la computadora, ingresar a la configuración de BIOS/UEFI, buscar una opción similar a Intel VT-x o AMD-V y establecerla en Enabled.

1.3 Habilitar las funciones relacionadas de Windows

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

Método A: A través de la interfaz gráfica (recomendado)

1. Presione Win + S, busque y abra "Activar o desactivar las funciones de Windows".
2. Marque los dos elementos 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 la computadora cuando se le solicite.

Método B: A través de la línea de comandos (con permisos 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

Después de la ejecución, reinicie la computadora manualmente.

1.4 Instalar o actualizar el kernel de WSL

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

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

1.5 Establecer WSL 2 como versión predeterminada

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

wsl --set-default-version 2

1.6 Problemas comunes

• Error 0x80370102: generalmente se debe 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 el comando esté disponible no significa que la instalación haya sido exitosa

Los comandos wsl --version, wsl -l -v y otros pueden ejecutarse correctamente, pero esto no significa que ya se cumplan las condiciones para instalar Linux. Ambas cosas se encuentran en etapas diferentes y no deben equipararse.

Que el comando esté disponible solo indica que:

• ✅ el componente WSL está habilitado/instalado en Windows
• ✅ 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 también requiere condiciones adicionales. Los puntos de bloqueo comunes son:

1. La virtualización está desactivada: VT-x / AMD-V no está habilitado en la BIOS/UEFI, WSL 2 no puede iniciarse, o se reporta un error de virtualización al instalar la distribución (método de verificación: ver 1.2 Habilitar la virtualización de hardware).
2. Versión/número de compilación de Windows demasiado bajo: WSL 2 tiene requisitos de kernel y versión; la edición Home o las imágenes empresariales demasiado antiguas pueden tener funciones incompletas (método de verificación: ver 1.1 Verificar los requisitos del sistema).
3. Aún no se ha instalado ninguna distribución de Linux: wsl -l -v solo lista las distribuciones instaladas; si no hay nada instalado, la lista estará vacía, lo que no significa que 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; la red de la empresa, los proxies y los firewalls pueden bloquear el proceso.
5. Permisos insuficientes: instalar una distribución o modificar la configuración de WSL requiere permisos de administrador.

TIP

En resumen: que el comando WSL funcione no significa que Linux esté listo; solo ha obtenido un "boleto de entrada", pero aún no ha instalado el sistema realmente.

3. Solución de problemas de instalación

Después de completar la configuración según el capítulo 1 (o si cree que ya la ha completado), si wsl --install sigue fallando, revise en el siguiente orden.

3.1 Hacer primero la verificación de un clic

Ejecute secuencialmente, con permisos de administrador, en PowerShell:

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

• ✅ Si ambos comandos se ejecutan correctamente, significa que los componentes opcionales de WSL están habilitados y las condiciones de virtualización están básicamente cumplidas.
• ❌ Si falla, se indicará directamente qué falta (por ejemplo, plataforma de máquina virtual, Hyper-V, virtualización de BIOS, etc.).

Luego ejecute systeminfo y confirme que Virtualization Enabled In Firmware: Yes aparece en la salida. Si ninguna de las comprobaciones anteriores reporta errores, en general puede ejecutar wsl --install con confianza para instalar una distribución.

NOTE

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

3.2 Lista de verificación manual

Si la verificación de un clic aún no logra localizar el problema, revise punto por punto:

1. Verificar si la virtualización de BIOS/firmware está habilitada: en PowerShell como administrador, ejecute systeminfo; la salida debe mostrar Virtualization Enabled In Firmware: Yes.
2. Verificar 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. Verificar si WSL está disponible: wsl --version debe producir una salida normal; si se indica que el comando no existe, el componente WSL no está instalado; vuelva al capítulo 1.
4. Verificar si WSL 2 está disponible (kernel y plataforma de máquina virtual): wsl --set-default-version 2 debe devolver éxito. Causas comunes de fallo: la plataforma de máquina virtual no está habilitada, o VT-x / AMD-V no está habilitado en la BIOS.

3.3 Referencia rápida de causas de fallo comunes

Situación	Explicación	Forma de solucionar
Virtualización no habilitada en la BIOS	Falla seguro	Reiniciar y habilitar VT-x / AMD-V en la BIOS (ver 1.2)
Windows 10 inferior a 19041	No admite wsl --install	Actualizar el sistema (ver 1.1)
Hyper-V / virtualización deshabilitada en el entorno empresarial	Puede fallar	Contactar al administrador del sistema
Edición Home antigua	Requiere instalación manual	Instalar manualmente el kernel de WSL según 1.4

3.4 Error 0xc03a0014: no se encuentra el proveedor de soporte de 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 de la pila de discos virtuales VHD/VHDX de Windows que no funciona correctamente: WSL 2 falla al registrar la distribución y al crear/montar ext4.vhdx.

Primero haga 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 y no en la distribución.

Verifique y repare en el siguiente orden:

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. Funciones de WSL / plataforma de máquina virtual no habilitadas (o sin efecto): vuelva a ejecutar los comandos de 1.3 Habilitar las funciones relacionadas de Windows 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 interfaz de administración de Hyper-V.

3. Faltan controladores/dispositivos de disco virtual: abra el Administrador de dispositivos y verifique si existen los siguientes elementos 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, una raw.img común, una ISO live ni un disco vacío formateado en NTFS/FAT. Los archivos .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 ni carpetas comprimidas; asegúrese de usar una PowerShell de administrador real (no una terminal normal).

6. Componentes del sistema dañados: ejecute DISM y SFC sucesivamente para reparar los componentes del sistema y luego 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/refuerzo de los programas de seguridad (como 360, Huorong) pueden interferir con las operaciones de disco virtual; puede desactivarlas temporalmente durante la resolución de problemas.