Intégration de WSL2 avec Docker sous Windows : un guide pratique et complet

Si vous travaillez sous Windows et souhaitez développer comme sous Linux, l'association de WSL 2 et Docker est l'une des meilleures solutions pour votre machine. Cette intégration vous permet d'exécuter des conteneurs Linux et Windows sur la même machine, de consommer moins de ressources et de bénéficier d'un démarrage des démons nettement plus rapide qu'avec d'autres options plus gourmandes en ressources.

Vous trouverez ci-dessous un guide complet pour configurer Docker Desktop avec WSL 2 comme backend , ou, si vous préférez, pour exécuter Docker directement dans WSL 2 sans passer par Docker Desktop. Vous découvrirez également comment l'utiliser avec Visual Studio Code, des conseils d'optimisation des performances, les chemins de stockage et une section de dépannage présentant les erreurs courantes et leurs solutions.

Conteneurs et WSL 2 : ce que vous devez savoir

Docker regroupe les applications et leurs dépendances dans des conteneurs afin qu'elles fonctionnent de la même manière dans n'importe quel environnement . Contrairement à une machine virtuelle traditionnelle, un conteneur ne nécessite pas de système d'exploitation complet : il partage le noyau de l'hôte et n'ajoute que les éléments manquants à votre application, ce qui réduit sa taille et accélère son exécution.

Comparée à une machine virtuelle, cette approche permet d'économiser de la mémoire et du processeur car elle n'exécute pas un système d'exploitation complet . Sous Windows, WSL 2 fournit un véritable noyau Linux avec prise en charge des appels système, ce qui permet à Docker de fonctionner nativement avec des performances optimales.

Un autre avantage clé est la disponibilité continue. Grâce aux conteneurs et aux orchestrateurs comme Kubernetes, vous pouvez mettre à jour les services version par version , remplacer les conteneurs à la volée et conserver plusieurs versions de sauvegarde sans interrompre l'ensemble du système.

En résumé, Docker favorise des environnements cohérents, minimise les conflits de dépendances et accélère les déploiements. Combiné à WSL 2 sous Windows, il vous permet de bénéficier d'un flux de travail Linux sans quitter votre bureau, grâce à l'intégration automatique des fichiers et des ports accessibles en local.

Prérequis Windows

Vérifiez que votre système Windows 10/11 respecte la configuration minimale requise : 64 bits, virtualisation activée dans le BIOS/UEFI et au moins 4 Go de RAM. Sur les versions récentes, l’activation de WSL et de sa plateforme de virtualisation est suffisante.

Pour activer les composants depuis PowerShell en tant qu'administrateur, vous pouvez utiliser des commandes telles que « enable WSL » et « Virtual Machine Platform ». Sur les systèmes mis à jour, le processus est simplifié grâce à WSL :

wsl --install

Si vous utilisez déjà WSL, définissez WSL 2 comme système par défaut et vérifiez ou migrez vos distributions installées :

wsl --set-default-version 2
wsl -l -v
wsl --set-version Ubuntu 2

Pour choisir la distribution par défaut avec laquelle vous effectuerez l'intégration, vous pouvez modifier la valeur par défaut si nécessaire :

wsl -s Ubuntu

Installez Docker Desktop avec un moteur basé sur WSL 2

La méthode la plus directe pour obtenir un environnement optimisé consiste à utiliser Docker Desktop avec un moteur WSL 2. Téléchargez le programme d'installation de Docker Desktop pour Windows, exécutez-le et suivez l'assistant. Si votre système le prend en charge, l'utilisation du moteur WSL 2 sera sélectionnée par défaut ; sinon, vous serez invité à l'activer lors de l'installation.

Après avoir lancé Docker Desktop, ouvrez son panneau Paramètres et, dans la section Général, activez l'option moteur basé sur WSL 2 si elle ne l'est pas déjà. Cela vous permettra d'exécuter des conteneurs Linux depuis Windows sans utiliser Hyper-V.

Ensuite, accédez à Paramètres > Ressources > Intégration WSL et activez l'intégration pour la ou les distributions WSL 2 que vous utiliserez (par exemple, Ubuntu). Si l'onglet Intégration WSL n'apparaît pas, vérifiez que vous êtes en mode conteneurs Linux et non en mode conteneurs Windows.

Pour vérifier que tout est en place, ouvrez votre distribution WSL (par exemple, Ubuntu) et exécutez les commandes de vérification :

docker --version
docker run hello-world

Cela confirme que le binaire de l'interface de ligne de commande et le démon répondent. Si vous parvenez à extraire l'image de test « hello-world », l'intégration fonctionne.

Développement dans des conteneurs avec Visual Studio Code

Avec WSL 2 et Docker opérationnels, l'expérience de développement est grandement améliorée grâce à Visual Studio Code et à ses trois extensions officielles : WSL, Dev Containers et Docker. Chacune apporte un élément essentiel pour travailler avec des conteneurs sous Windows.

Installez l'extension WSL pour ouvrir directement les dossiers de votre distribution dans VS Code. Vous éviterez ainsi les problèmes de chemins d'accès, de fichiers binaires incompatibles et de permissions entre systèmes.

Installez Dev Containers pour ouvrir le dossier de votre projet dans un conteneur et développer dans l' environnement défini par un fichier Dockerfile et un fichier devcontainer.json. C'est un moyen pratique d'uniformiser les outils et les dépendances au sein de votre équipe.

Installez également l'extension Docker pour compiler, exécuter et gérer des images, des conteneurs et des volumes directement depuis la barre latérale de VS Code . Cela simplifie considérablement les tâches quotidiennes sans quitter l'éditeur.

Un flux de travail typique serait le suivant : cloner le projet dans WSL, l’ouvrir avec code .et lancez l'action Dev Containers dans la palette de commandes pour Rouvrir dans le conteneurVS Code générera un dossier .devcontainer contenant votre Dockerfile et votre fichier devcontainer.json adaptés à votre pile technologique (par exemple, Python/Django) et construira l'image.

Vérifiez que vous utilisez toujours Linux dans le terminal intégré à VS Code : uname y python3 --versionVous verrez Linux (WSL 2) et la version de Python défini par le conteneur, qui peut différer de celui de votre distribution. Avec la configuration de Exécuter et déboguer (par exemple, avec un profil Django), vous pourrez exécuter et déboguer votre application dans le conteneur, en accédant à l'URL locale que j'indique, généralement http://127.0.0.1:8000/.

Exécuter Docker sans Docker Desktop : Installation directe dans WSL 2

Si vous souhaitez éviter Docker Desktop pour des raisons de licence ou par préférence personnelle, vous pouvez installer Docker Engine au sein de votre distribution WSL 2. Sous Ubuntu, mettez à jour les paquets, ajoutez le dépôt officiel et procédez à l'installation des composants nécessaires.

sudo apt update && sudo apt upgrade

source /etc/os-release
curl -fsSL https://download.docker.com/linux/${ID}/gpg | sudo apt-key add -
echo "deb [arch=amd64] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

Pour éviter d'avoir à ajouter `sudo` avant chaque commande, ajoutez votre utilisateur au groupe `docker` et reconnectez-vous à la distribution :

sudo usermod -aG docker $USER

Démarrez le démon lorsque vous en avez besoin dans WSL 2 avec :

sudo dockerd

Si vous voyez un message du type « API listen on /var/run/docker.sock » , le serveur est en cours d'exécution. Ouvrez un autre terminal sur votre distribution et vérifiez que tout répond correctement :

docker run --rm hello-world

Utilisation de l'interface de ligne de commande Docker depuis Windows avec Docker dans WSL 2

Pour exécuter Docker et Docker Compose depuis Windows alors que le démon s'exécute dans WSL 2, téléchargez docker.exe et docker-compose.exe et ajoutez-les à votre variable d'environnement PATH. Vous pourrez ainsi exécuter des commandes PowerShell ou VS Code dans les terminaux Windows.

Vous pouvez créer un script PowerShell qui récupère l'adresse IP de la distribution WSL 2 et démarre le démon à l'écoute sur TCP, en configurant la variable d'environnement DOCKER_HOST dans Windows. Voici un exemple de fonctionnement :

$ip = (wsl sh -c "hostname -I").Split(" ")[0]
$DOCKER_HOST = "tcp://" + $ip + ":2375"
[System.Environment]::SetEnvironmentVariable('DOCKER_HOST',$DOCKER_HOST,[System.EnvironmentVariableTarget]::User)
wsl sh -c "sudo dockerd --tls=false -H tcp://$ip"

Vous verrez des avertissements indiquant que l'ouverture du démon sans TLS est non sécurisée . Cette configuration est exclusivement réservée au développement local ; ne l'utilisez pas en production. Vous pouvez essayer la commande suivante dans une autre fenêtre PowerShell :

docker version
docker container ls
docker run --rm hello-world
docker run -it --rm -p 8080:80 uzyexe/tetris

Si vous devez orchestrer plusieurs services, docker-compose reste une solution viable. Par exemple, avec un fichier d'exemple, vous pouvez lancer une application utilisant une base de données et vérifier la configuration des ports en accédant à localhost sur le port exposé.

Paramètres courants dans docker-compose sans Docker Desktop

Lorsque vous travaillez sans Docker Desktop, certaines automatisations ne sont plus disponibles. Il est donc conseillé de modifier deux éléments dans votre fichier docker-compose.yml :

• Dans les volumes qui utilisent l'accent tonique pour la maison ~Remplacez-le par votre chemin d'accès personnel réel dans WSL 2, par exemple. /mnt/c/Users/tu-usuario si vous pointez vers des fichiers situés dans C: depuis la distribution.
• Ajouter la section extra_hosts lorsque votre projet dépend de l'alias host.docker.internal:

extra_hosts:
- host.docker.internal:host-gateway

Cela vous permet d'éviter les surprises liées à la connectivité entre les conteneurs et l'hôte, en reproduisant les fonctionnalités offertes par défaut par Docker Desktop.

Performances et bonnes pratiques avec WSL 2

Docker Desktop sur WSL 2 utilise l'allocation dynamique de mémoire , ne consommant que la mémoire nécessaire et accélérant ainsi les opérations intensives telles que les compilations. De plus, le démarrage à froid du démon est nettement plus rapide qu'avec les solutions alternatives basées sur des machines virtuelles classiques.

La règle d'or : conservez vos fichiers de projet dans le Système de fichiers WSL 2Travaillez à partir de /home/tu-usuario Dans cette distribution, évitez les pénalités d'E/S qui apparaissent lors du montage de chemins Windows sous /mnt/c pour les tâches nécessitant de nombreux accès disque.

Dans Docker Desktop, assurez-vous que l'option « Utiliser un moteur basé sur WSL 2 » est activée et que l'intégration de la distribution appropriée est bien configurée dans Paramètres > Ressources > Intégration WSL. Une fois ces étapes effectuées et vos projets déplacés vers le bon emplacement, la différence de performances sera très perceptible.

Si les politiques de votre entreprise exigent une isolation renforcée, envisagez d'utiliser le mode Hyper-V dans Docker Desktop ou d'activer l'isolation renforcée des conteneurs. Pour la plupart des scénarios de développement, WSL 2 offre un excellent compromis entre performances et simplicité.

Dossiers de stockage et raccourcis utiles

Docker Desktop crée deux distributions WSL internes pour vos données : docker-desktop et docker-desktop-data . Vous pouvez accéder à leurs dossiers depuis Windows via des chemins UNC si nécessaire pour en examiner le contenu.

Une astuce pratique : depuis le lancement de votre distribution WSL explorer.exe . Pour ouvrir le répertoire courant dans l'Explorateur de fichiers, vous pouvez également accéder directement aux points de montage persistants avec :

\\wsl$\<Distro>\mnt\wsl

Remplacez <Distro> par le nom de votre distribution, tel que Ubuntu-24.04, pour trouver les emplacements internes où WSL expose ses volumes et où Docker Desktop stocke les données lors de l'utilisation de WSL 2.

Dépannage des problèmes courants

Si vous utilisez une version antérieure de l'intégration, il se peut qu'un ancien contexte Docker nommé « wsl » soit encore présent et ne soit plus utilisé . Vérifiez vos contextes et supprimez-le pour éviter les erreurs.

docker context ls
docker context rm wsl

Ce contexte obsolète peut provoquer des messages d'erreur lors de l'ouverture de pipes docker_wsl sous Windows. Sa suppression rétablit la configuration par défaut, compatible avec Windows et WSL 2.

Si la section « Intégration WSL » n'apparaît pas dans Docker Desktop, vous êtes peut-être en mode conteneurs Windows . Passez en mode conteneurs Linux via l'icône dans la barre d'état système. Retournez ensuite dans les paramètres pour activer l'intégration.

N'oubliez pas que WSL expose le système de fichiers à l'hôte dans \\wsl$\Ce problème n'est pas propre à Docker Desktop ; il fait partie du modèle d'interopérabilité WSL. Docker Desktop, quant à lui, fonctionne sur sa propre distribution interne. docker-desktop, avec le même niveau d'isolation que toute autre distribution WSL ; elle n'interagit avec les autres que lorsque vous activez l'intégration WSL.

Pour renforcer la sécurité de votre environnement, envisagez d'utiliser Hyper-V ou des stratégies d'isolation avancées des conteneurs. Pour le développement courant, WSL 2 est suffisant, mais certaines organisations privilégient une protection supplémentaire en fonction de leur niveau de risque.

Avec tout ce qui précède, vous disposez désormais d'une vue d'ensemble complète pour choisir votre méthode de travail : utiliser Docker Desktop avec le moteur WSL 2 pour une expérience guidée et stable, ou installer Docker directement sur WSL 2 pour réduire les dépendances externes ; si vous combinez également VS Code, ses extensions et hébergez les projets dans le système de fichiers WSL, vous bénéficierez d'un environnement agile et cohérent, avec des contrôles de performance précis, des chemins de données clairs et des solutions immédiates aux erreurs courantes.