Configurer WSL

Avant d'utiliser WSL Dashboard, votre système Windows doit avoir l'environnement WSL 2 correctement activé et configuré. Ce document est divisé en trois grandes parties :

1. Activer et configurer WSL : installation et configuration de base de WSL 2.
2. Un commande disponible ne signifie pas une installation réussie : explique que pouvoir exécuter la commande wsl ne signifie pas que Linux peut être installé avec succès.
3. Résolution des échecs d'installation : méthodes de vérification et de réparation lorsque l'installation échoue encore après la configuration.

1. Activer et configurer WSL

Ce chapitre vous guide à travers la configuration de base nécessaire. Après l'avoir terminé, lisez le chapitre 2 pour comprendre la différence entre la disponibilité de la commande et la réussite de l'installation ; si l'installation pose toujours problème, consultez le chapitre 3.

1.1 Vérifier la configuration requise

WSL 2 a des exigences minimales sur la version de Windows. Appuyez sur Win + R et entrez winver pour vérifier votre version :

• Windows 10 : version 1903 ou ultérieure, avec un numéro de build (Build) d'au moins 18362.
• Windows 11 : toutes les versions sont prises en charge.

IMPORTANT

Si votre version est trop ancienne, mettez d'abord à niveau votre système via « Windows Update ».

1.2 Activer la virtualisation matérielle

WSL 2 repose sur la technologie de virtualisation ; vous devez donc activer la technologie de virtualisation (Virtualization Technology) dans la BIOS/UEFI de la carte mère.

• Méthode de vérification : ouvrez le « Gestionnaire des tâches » -> onglet « Performances » -> « CPU ».
• Vérifier l'état : confirmez que l'état « Virtualisation » en bas à droite affiche « Activée ».
• Comment l'activer : si elle n'est pas activée, redémarrez l'ordinateur, entrez dans la configuration BIOS/UEFI, recherchez une option similaire à Intel VT-x ou AMD-V et définissez-la sur Enabled.

1.3 Activer les fonctionnalités Windows associées

Vous devez activer les fonctionnalités « Sous-système Windows pour Linux » et « Plateforme de machine virtuelle » de Windows.

Méthode A : via l'interface graphique (recommandée)

1. Appuyez sur Win + S, recherchez et ouvrez « Activer ou désactiver des fonctionnalités Windows ».
2. Cochez les deux éléments suivants :
   • Sous-système Windows pour Linux (Windows Subsystem for Linux)
   • Plateforme de machine virtuelle (Virtual Machine Platform)
3. Cliquez sur « OK » et redémarrez l'ordinateur lorsque vous y êtes invité.

Méthode B : via la ligne de commande (privilèges d'administrateur)

Exécutez PowerShell en tant qu'administrateur et exécutez les commandes suivantes :

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

# Activer la plateforme de machine virtuelle
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Après l'exécution, redémarrez l'ordinateur manuellement.

1.4 Installer/mettre à jour le noyau WSL

Les versions modernes de Windows peuvent obtenir les mises à jour de WSL via le Microsoft Store.

• Adresse de téléchargement : Microsoft Store - Windows Subsystem for Linux
• Téléchargement manuel : si vous ne pouvez pas utiliser le magasin, téléchargez le paquet .msixbundle ou .msi le plus récent depuis WSL GitHub Releases pour une installation hors ligne.

1.5 Définir WSL 2 comme version par défaut

Pour garantir que les nouvelles distributions installées utilisent WSL 2 par défaut, exécutez dans le terminal :

wsl --set-default-version 2

1.6 Questions fréquentes

• Erreur 0x80370102 : généralement due à la virtualisation non activée dans la BIOS ou à un conflit avec Hyper-V.
• Bascule entre WSL 1 et WSL 2 : vous pouvez utiliser wsl --set-version <nom-de-la-distribution> 2 pour mettre à niveau une instance existante de WSL 1 vers WSL 2.

2. Une commande disponible ne signifie pas une installation réussie

Le fait que des commandes comme wsl --version ou wsl -l -v s'exécutent correctement ne signifie pas que les conditions d'installation de Linux sont réunies. Ce sont des étapes différentes qui ne doivent pas être confondues.

Une commande disponible signifie seulement :

• ✅ Les composants WSL de Windows sont activés/installés
• ✅ L'outil en ligne de commande wsl.exe est disponible
• ✅ Le système reconnaît les commandes liées à WSL

Mais installer avec succès une distribution Linux nécessite des conditions supplémentaires. Les points de blocage courants sont :

1. Virtualisation désactivée : VT-x / AMD-V n'est pas activé dans la BIOS/UEFI, WSL 2 ne peut pas démarrer, ou une erreur de virtualisation est signalée lors de l'installation de la distribution (méthode de vérification au 1.2 Activer la virtualisation matérielle).
2. Version/build de Windows trop ancien : WSL 2 exige un certain noyau et une certaine version ; l'édition Famille ou les images d'entreprise trop anciennes peuvent manquer de fonctionnalités (méthode de vérification au 1.1 Vérifier la configuration requise).
3. Aucune distribution Linux réellement installée : wsl -l -v ne liste que les distributions installées ; si rien n'est installé, la liste est vide, ce qui ne signifie pas que vous pouvez exécuter Ubuntu directement.
4. Problèmes de réseau / Microsoft Store : wsl --install -d <distribution> doit récupérer l'image depuis le magasin ou le réseau ; les réseaux d'entreprise, les proxys et les pare-feu peuvent bloquer.
5. Permissions insuffisantes : installer des distributions ou modifier les paramètres WSL nécessite des privilèges d'administrateur.

TIP

En résumé : les commandes WSL fonctionnent ≠ Linux prêt ; vous n'avez obtenu que le « billet d'entrée », le système n'est pas encore installé.

3. Résolution des échecs d'installation

Après avoir suivi le chapitre 1 (ou si vous pensez l'avoir fait), si wsl --install échoue toujours, vérifiez les points suivants dans l'ordre.

3.1 Commencez par la « vérification en un clic »

Exécutez PowerShell en tant qu'administrateur et exécutez successivement :

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

• ✅ Si ces deux commandes s'exécutent sans problème, les composants facultatifs WSL sont activés et les conditions de virtualisation sont globalement réunies.
• ❌ Si elles échouent, le message indiquera directement ce qui manque (plateforme de machine virtuelle, Hyper-V, virtualisation BIOS, etc.).

Exécutez ensuite systeminfo et confirmez la présence de Virtualization Enabled In Firmware: Yes dans la sortie. Si rien ne signale d'erreur, vous pouvez exécuter wsl --install en toute confiance pour installer la distribution.

NOTE

Aucune commande ne peut garantir à 100 % le succès de wsl --install, mais les vérifications ci-dessus confirment que les conditions d'installation sont réunies.

3.2 Liste de vérification manuelle

Si la « vérification en un clic » ne parvient toujours pas à localiser le problème, vérifiez point par point :

1. Vérifier si la virtualisation BIOS/firmware est activée : dans PowerShell administrateur, exécutez systeminfo ; la sortie doit contenir Virtualization Enabled In Firmware: Yes.
2. Vérifier si les fonctionnalités Windows sont activées :

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

   L'état des deux commandes doit être Enabled.
3. Vérifier si WSL est disponible : wsl --version doit produire une sortie normale ; si la commande est introuvable, les composants WSL ne sont pas installés ; revenez au chapitre 1.
4. Vérifier si WSL 2 peut être utilisé (noyau et plateforme de machine virtuelle) : wsl --set-default-version 2 doit réussir. Causes d'échec courantes : la plateforme de machine virtuelle n'est pas activée, ou VT-x / AMD-V n'est pas activé dans la BIOS.

3.3 Référence rapide des causes d'échec courantes

Situation	Description	Solution
Virtualisation désactivée dans la BIOS	Échec garanti	Redémarrez, entrez dans la BIOS et activez VT-x / AMD-V (voir 1.2)
Windows 10 antérieur à 19041	wsl --install non pris en charge	Mettez à niveau le système (voir 1.1)
Environnement d'entreprise avec Hyper-V/virtualisation désactivée	Peut échouer	Contactez l'administrateur système
Édition Famille ancienne	Installation manuelle requise	Installez manuellement le noyau WSL selon 1.4

3.4 Erreur 0xc03a0014 : fournisseur de support de disque virtuel introuvable

Le message d'erreur est Cannot find a virtual disk support provider for the specified file. Ce n'est pas un problème de la distribution Linux elle-même, mais la pile de disques virtuels VHD/VHDX de Windows ne fonctionne pas correctement ; WSL 2 échoue lors de l'enregistrement de la distribution ou de la création/montage de ext4.vhdx.

Faites d'abord une vérification minimale : exécutez PowerShell en tant qu'administrateur et testez New-VHD (par exemple New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Si cette commande signale également la même erreur, le problème vient à 100 % de Windows, pas de la distribution.

Suivez l'ordre suivant pour diagnostiquer et réparer :

1. Le service Virtual Disk n'est pas en cours d'exécution : ouvrez services.msc, recherchez le service Virtual Disk, définissez son type de démarrage sur « Automatique » et démarrez-le.

2. Les fonctionnalités WSL / Plateforme de machine virtuelle ne sont pas activées (ou n'ont pas pris effet) : réexécutez les commandes de 1.3 Activer les fonctionnalités Windows associées, puis redémarrez obligatoirement. L'édition Famille de Windows n'a pas d'Hyper-V complet, mais WSL 2 n'a besoin que de la plateforme de machine virtuelle, pas de la console de gestion Hyper-V.

3. Pilotes/périphériques de disque virtuel manquants : ouvrez le Gestionnaire de périphériques et vérifiez si les éléments suivants existent dans « Périphériques système / Contrôleurs de stockage » :

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

   S'ils manquent, vous pouvez les ajouter manuellement via hdwwiz.exe (Contrôleurs de stockage → Microsoft → Microsoft VHD Loopback Controller) et confirmez que le service FsDepends n'est pas désactivé.

4. L'image importée ne respecte pas les exigences WSL : avec wsl --import --vhd, le VHDX doit être un système de fichiers ext4 ; pas un disque chiffré LUKS, un raw.img ordinaire, un Live ISO ni un disque vide formaté en NTFS/FAT. .img / .qcow2 / .iso ne peuvent pas être utilisés directement avec wsl --import --vhd.

5. Problèmes de chemin/permissions/système de fichiers : le répertoire de destination doit se trouver sur un disque NTFS (FAT32/exFAT ne conviennent pas) ; évitez les caractères chinois, les espaces et les symboles spéciaux dans le chemin ; n'importez pas depuis des lecteurs réseau, OneDrive ou des dossiers compressés ; utilisez toujours un vrai PowerShell administrateur (pas un terminal ordinaire).

6. Composants système endommagés : exécutez DISM puis SFC pour réparer les composants système, puis réessayez :

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

TIP

Les machines virtuelles tierces (VirtualBox, VMware) ou les fonctions de sandbox/renforcement des logiciels de sécurité (comme 360, Huorong) peuvent interférer avec les opérations de disque virtuel ; vous pouvez les désactiver temporairement pendant le dépannage.