Comment synchroniser WSL2 et le fichier hosts Windows (Guide 2026)

Réponse directe : Pour mapper des domaines locaux personnalisés (app.test, api.test) vers des serveurs exécutés dans WSL2 sous Windows 11, ajoutez vos entrées dans le fichier hosts de Windows (C:\Windows\System32\drivers\etc\hosts) en pointant vers 127.0.0.1, et assurez-vous que le transfert localhost est activé dans votre fichier .wslconfig.

# Dans C:\Windows\System32\drivers\etc\hosts
127.0.0.1   app.test
127.0.0.1   api.test

Puisque WSL2 fonctionne dans une machine virtuelle légère avec une IP NAT dynamique, comprendre comment Windows gère le bouclage local permet d'éviter les erreurs de connexion récurrentes.

Le défi réseau de WSL2 : NAT vs Bouclage Local

Contrairement à WSL1 (qui partageait directement la pile réseau de Windows), WSL2 utilise un véritable noyau Linux dans une VM gérée par Hyper-V.

Étape 1 : Configurer .wslconfig pour le transfert localhost

Windows intègre un service de relais automatique qui redirige le trafic envoyé vers 127.0.0.1 sur l'hôte vers les ports actifs dans WSL2.

Ouvrez ou créez le fichier de configuration global de WSL sous Windows :

%USERPROFILE%\.wslconfig
(Exemple : C:\Users\VotreNomUtilisateur\.wslconfig)

Ajoutez la configuration suivante :

[wsl2]
localhostForwarding=true

# Optionnel pour Windows 11 23H2 / 24H2 et plus récent :
# networkingMode=mirrored
# dnsTunneling=true

Redémarrez WSL pour appliquer les paramètres :

# Dans PowerShell (Administrateur) sous Windows
wsl --shutdown

Étape 2 : Configurer votre serveur de dev sur 0.0.0.0

Un piège classique : de nombreux outils (Vite, Next.js, Express, Django) n'écoutent par défaut que sur 127.0.0.1 à l'intérieur de Linux. Puisque Windows communique à travers l'interface virtuelle, le serveur doit écouter sur toutes les interfaces (0.0.0.0).

Configuration Vite (`vite.config.ts`)

export default defineConfig({
  server: {
    host: '0.0.0.0', // ou ajoutez --host dans package.json
    port: 3000,
  },
});

Configuration Next.js

# Dans package.json
"scripts": {
  "dev": "next dev -H 0.0.0.0 -p 3000"
}

Étape 3 : Ajouter les domaines personnalisés dans le fichier hosts Windows

Ouvrez le fichier hosts de Windows avec les privilèges administrateur :

C:\Windows\System32\drivers\etc\hosts

Ajoutez vos noms de domaines de développement :

# Projets de développement WSL2
127.0.0.1   monapp.test
127.0.0.1   api.monapp.test
127.0.0.1   admin.monapp.test

*(Nous conseillons d'utiliser l'extension réservée .test pour éviter les conflits avec de vrais domaines publics. Voir pourquoi utiliser le TLD .test en local.)*

Étape 4 : Vider le cache DNS de Windows

Après avoir sauvegardé le fichier hosts, videz le cache du résolveur DNS de Windows :

# Dans PowerShell en tant qu'Administrateur
ipconfig /flushdns
Clear-DnsClientCache

Ouvrez maintenant http://monapp.test:3000 dans votre navigateur sous Windows. Vos requêtes atteindront directement votre serveur Linux WSL2.

Synchronisation automatique de /etc/hosts dans WSL2

Par défaut, WSL2 génère son propre fichier /etc/hosts interne au démarrage en copiant les entrées du fichier hosts de Windows.

Ce comportement est géré dans votre distribution Linux par /etc/wsl.conf :

# Dans /etc/wsl.conf sous votre Linux WSL2
[network]
generateHosts = true
generateResolvConf = true

Quand generateHosts = true, chaque entrée ajoutée sous Windows est répercutée dans le terminal Linux. Cela signifie que curl http://monapp.test:3000 fonctionne aussi bien depuis Windows que depuis le terminal Ubuntu.

Mode Avancé : Mode Réseau en Miroir (Windows 11 24H2)

Si vous utilisez Windows 11 (build 22621+ ou 24H2), Microsoft a introduit le mode réseau en miroir (Mirrored Networking). Ce mode partage directement les interfaces réseau de Windows avec Linux, supprimant totalement la couche NAT.

Dans %USERPROFILE%\.wslconfig :

[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

Avantages du mode miroir :

• Aucune latence de translation NAT.
• Les processus Linux se lient directement à 127.0.0.1 sur Windows.
• Compatibilité parfaite avec les VPN d'entreprise.

Dépannage des problèmes courants WSL2 et hosts

1. Connexion refusée sur http://monapp.test

• Vérifiez que votre serveur de dev est bien lancé et écoute sur 0.0.0.0.
• Vérifiez si un autre processus Windows utilise déjà le port avec netstat -ano | findstr :3000 dans PowerShell.
• Consultez notre guide sur la résolution des erreurs de connexion refusée.

2. Le navigateur affiche l'ancienne IP ou le site en ligne

• Videz le cache DNS interne de Chrome sur chrome://net-internals/#dns.
• Videz le cache DNS Windows avec ipconfig /flushdns.
• Consultez pourquoi les modifications du fichier hosts ne sont pas prises en compte.

3. Conteneurs Docker dans WSL2

• Quand vous utilisez Docker dans WSL2, utilisez --add-host monapp.test:host-gateway ou extra_hosts dans docker-compose.yml pour router les conteneurs vers les services hôtes.
• Voir aussi : gérer le fichier hosts avec Docker.

Automatiser WSL2 et les fichiers hosts avec Sleezr

Gérer manuellement des dizaines d'entrées pour plusieurs clients sous WSL2, Docker et Windows peut vite devenir complexe.

Sleezr simplifie votre quotidien :

• Basculez entre différents environnements de projets en un clic.
• Vidage automatique du cache DNS à chaque bascule.
• Sauvegardes automatiques avant chaque écriture.
• Support multi-plateforme complet pour Windows, macOS et Linux.

Découvrez le guide complet pour modifier le fichier hosts sous Windows 11 ou découvrez notre comparatif Sleezr vs PowerToys Hosts.

_Testé en août 2026 sur Windows 11 24H2 avec WSL2 Ubuntu 24.04 LTS._

Sources et lectures complémentaires

• Documentation Microsoft : Configuration avancée de WSL
• Documentation Microsoft : Accéder aux applications réseau avec WSL
• RFC 6761 : Noms de domaine à usage spécial
• Le fichier hosts expliqué (Wikipédia)