Tutoriel 📝 Résoudre les incompatibilités entre WSL2 et Docker Desktop

[Sylvain*]

Résoudre les incompatibilités entre WSL2 et Docker Desktop

Introduction

Ce tutoriel vous aide à corriger les conflits rencontrés lors de l’utilisation conjointe de WSL2 (Windows Subsystem for Linux v2) et de Docker Desktop. Il arrive que Docker ne parvienne pas à démarrer, que les conteneurs ne fonctionnent pas correctement ou que le backend WSL2 provoque des erreurs réseau, de montée de version ou de compatibilité.

---

Prérequis

• Windows 10 2004+ ou Windows 11 avec WSL2 activé

• Docker Desktop 4.x+ installé

• Accès administrateur

---

Différentes Approches

• Approche #1 : Vérification des prérequis système et versions

• Approche #2 : Réinitialisation de l’intégration entre Docker et WSL2

• Approche #3 : Script PowerShell pour reconfigurer les environnements WSL

---

Niveau de difficulté

• Approche #1 : Facile

• Approche #2 : Intermédiaire

• Approche #3 : Avancé

---

Les Avantages

• Approche #1 : Prévention des erreurs d’environnement

• Approche #2 : Réparation rapide sans perte de données

• Approche #3 : Automatisation complète de la réparation

---

Les Inconvénients

• Approche #1 : Ne résout pas les problèmes déjà présents

• Approche #2 : Requiert un redémarrage de Docker

• Approche #3 : Supprime et réinstalle les distributions si mal utilisé

---

Approche #1

Vérifier que WSL2 est installé et utilisé par défaut

wsl --list --verbose

Vérifier la version par défaut :

wsl --set-default-version 2

Mettre à jour WSL si nécessaire :

wsl --update

Vérifier la version du noyau WSL :

wsl --status

S'assurer que la fonctionnalité Hyper-V et Virtual Machine Platform sont activées :

dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism /online /enable-feature /featurename:Microsoft-Hyper-V-All /all /norestart

---

Approche #2

Ouvrir Docker Desktop

Aller dans Settings → General

Cocher Use the WSL 2 based engine

Aller dans Resources > WSL Integration

Activer l’intégration uniquement pour les distributions utilisées

Redémarrer Docker Desktop

---

Approche #3

Créer un script Fix-WslDocker.ps1

Contenu du script :

Forcer le WSL2 par défaut
wsl --set-default-version 2

Réparer l'intégration Docker
Stop-Process -Name "Docker Desktop" -Force
Start-Sleep -Seconds 3
wsl --shutdown
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

Exécuter avec PowerShell admin :

powershell -ExecutionPolicy Bypass -File Fix-WslDocker.ps1

---

Astuce

Évitez d’intégrer toutes les distributions WSL dans Docker. Cela limite les risques de conflit et les surcharges mémoire.

---

Mise en garde

Ne mélangez pas les installations Docker en mode Windows et mode WSL2. Désinstallez toute ancienne version de Docker Toolbox ou backend Hyper-V natif.

---

Conseil

Utilisez la commande

docker context ls

pour vérifier si le bon backend WSL est actif et éviter les erreurs de contexte.

---

Solution alternative

• Rancher Desktop – Alternative à Docker Desktop avec WSL2 support natif

• Podman – Conteneurisation sans daemon compatible Docker CLI

---

Références

• Support Microsoft

• Microsoft Learn

• Recherche Google

• Recherche Github

---

Conclusion

Les conflits entre WSL2 et Docker Desktop proviennent généralement de mauvaises intégrations, de versions incompatibles ou de restes d’installations précédentes. En vérifiant les prérequis, en réinitialisant proprement l’intégration et en utilisant des scripts PowerShell adaptés, vous pouvez restaurer une coexistence stable entre les deux environnements.