Activer et configurer WSL

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

1. Activer et configurer WSL : effectuer l'installation et la configuration de base de WSL 2.
2. Une commande disponible ne signifie pas une installation réussie : explique que l'exécution de la commande wsl ne signifie pas que Linux peut être installé avec succès.
3. Dépannage de l'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 guidera dans la réalisation des réglages de base nécessaires. Après avoir terminé ce chapitre, veuillez lire le chapitre 2 pour comprendre la différence entre la disponibilité d'une commande et le succès de l'installation ; si l'installation pose toujours problème, reportez-vous au chapitre 3.

1.1 Vérifier les exigences du système

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

• Windows 10 : version 1903 ou supérieure, et le numéro de build doit être 18362 ou supérieur.
• Windows 11 : toutes les versions sont prises en charge.

IMPORTANT

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

1.2 Activer la virtualisation matérielle

WSL 2 fonctionne sur la base de la technologie de virtualisation. Vous devez donc activer Virtualization Technology dans le BIOS/UEFI de la carte mère.

• Méthode de vérification : ouvrez le « Gestionnaire des tâches » -> onglet « Performance » -> « CPU ».
• Vérifier l'état : confirmez que l'état « Virtualisation » en bas à droite affiche « Activé ».
• Mode d'activation : si elle n'est pas activée, vous devez redémarrer l'ordinateur, accéder aux paramètres BIOS/UEFI, trouver une option similaire à Intel VT-x ou AMD-V et la définir 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é)

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 (avec droits d'administrateur)

Exécutez PowerShell en tant qu'administrateur, puis 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 manuellement l'ordinateur.

1.4 Installer ou 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 Store, vous pouvez télécharger le dernier package d'installation .msixbundle ou .msi 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 Problèmes courants

• Erreur 0x80370102 : généralement due au fait que la virtualisation n'est pas activée dans le 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 WSL 1 existante vers WSL 2.

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

wsl --version, wsl -l -v et d'autres commandes peuvent s'exécuter normalement, mais cela ne signifie pas que les conditions pour installer Linux sont réunies. Les deux se situent à des étapes différentes et ne doivent pas être assimilées.

Une commande disponible signifie seulement que :

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

Mais l'installation réussie d'une distribution Linux nécessite encore des conditions supplémentaires. Les points de blocage courants sont les suivants :

1. La virtualisation est désactivée : VT-x / AMD-V n'est pas activé dans le 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 : voir 1.2 Activer la virtualisation matérielle).
2. Version / build de Windows trop ancien : WSL 2 a des exigences concernant le noyau et la version ; les éditions Famille et certaines images d'entreprise trop anciennes peuvent manquer de fonctionnalités (méthode de vérification : voir 1.1 Vérifier les exigences du système).
3. Aucune distribution Linux réellement installée : wsl -l -v ne répertorie que les distributions installées ; si rien n'est installé, la liste est vide, ce qui ne signifie pas que vous pouvez lancer Ubuntu directement.
4. Problèmes de réseau / Microsoft Store : wsl --install -d <distribution> doit télécharger l'image depuis le Store ou le réseau ; le réseau d'entreprise, les proxys et les pare-feu peuvent tous bloquer le téléchargement.
5. Permissions insuffisantes : l'installation d'une distribution ou la modification des paramètres WSL nécessite des droits d'administrateur.

TIP

En résumé : une commande WSL disponible ne signifie pas que Linux est prêt ; vous n'avez obtenu qu'un « billet d'entrée », mais vous n'avez pas encore réellement installé le système.

3. Dépannage de l'installation

Après avoir terminé la configuration conformément au chapitre 1 (ou si vous pensez l'avoir terminée), si l'exécution de wsl --install échoue toujours, vérifiez dans l'ordre suivant.

3.1 Commencer par le test en une seule commande

Exécutez successivement, avec des droits d'administrateur, dans PowerShell :

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

• ✅ Si ces deux commandes s'exécutent correctement, cela signifie que les composants facultatifs de WSL sont activés et que les conditions de virtualisation sont globalement réunies.
• ❌ En cas d'échec, le message indiquera directement ce qui manque (par exemple, plateforme de machine virtuelle, Hyper-V, virtualisation BIOS, etc.).

Exécutez ensuite systeminfo et confirmez que Virtualization Enabled In Firmware: Yes apparaît dans la sortie. Si aucune erreur n'est signalée, vous pouvez en général exécuter wsl --install en toute confiance pour installer une distribution.

NOTE

Aucune commande ne peut garantir à 100 % que wsl --install réussira, mais les vérifications ci-dessus permettent de confirmer que les conditions d'installation sont réunies.

3.2 Liste de contrôle manuelle

Si le test en une seule commande ne permet toujours pas d'identifier le problème, vérifiez point par point :

1. Vérifier si la virtualisation BIOS/firmware est activée : exécutez systeminfo dans PowerShell en administrateur ; 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 renvoyé par les deux commandes doit être Enabled.
3. Vérifier si WSL est disponible : wsl --version doit produire une sortie normale ; si le message indique que la commande n'existe pas, cela signifie que le composant WSL n'est pas installé ; revenez au chapitre 1.
4. Vérifier si WSL 2 est disponible (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 le BIOS.

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

Situation	Explication	Traitement
Virtualisation non activée dans le BIOS	Échec garanti	Redémarrer et activer VT-x / AMD-V dans le BIOS (voir 1.2)
Windows 10 inférieur à 19041	wsl --install non pris en charge	Mettre à jour le système (voir 1.1)
Hyper-V / virtualisation désactivée dans l'environnement d'entreprise	Échec possible	Contacter l'administrateur système
Ancienne édition Famille	Installation manuelle requise	Installer manuellement le noyau WSL conformément au 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 de la pile de disques virtuels VHD/VHDX de Windows qui ne fonctionne pas correctement : WSL 2 échoue lors de l'enregistrement de la distribution et de la création/montage d'ext4.vhdx.

Commencez par 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 est à 100 % du côté de Windows et non de la distribution.

Vérifiez et réparez dans l'ordre suivant :

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 du 1.3 Activer les fonctionnalités Windows associées, puis redémarrez obligatoirement. L'édition Famille de Windows ne dispose pas d'Hyper-V complet, mais WSL 2 n'a besoin que de la plateforme de machine virtuelle, et non de l'interface de gestion d'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 sont présents 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 de WSL : lors de l'utilisation de wsl --import --vhd, le VHDX doit être un système de fichiers ext4 ; il ne peut pas s'agir d'un disque chiffré LUKS, d'une raw.img ordinaire, d'une ISO live ou d'un disque vide formaté en NTFS/FAT. Les fichiers .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 cible 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 un lecteur réseau, OneDrive ou un dossier compressé ; utilisez impérativement une véritable console PowerShell d'administrateur (et non un terminal ordinaire).

6. Composants système endommagés : exécutez successivement DISM et 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 bac à sable/renforcement des logiciels de sécurité (telles que 360, Huorong) peuvent interférer avec les opérations de disque virtuel ; vous pouvez les désactiver temporairement lors du dépannage.