How to Sync WSL2 with Windows Hosts File for Local Domains (2026)

Direct answer: To map custom local domains (app.test, api.test) to servers running inside WSL2 on Windows 11, add your entries to the Windows hosts file (C:\Windows\System32\drivers\etc\hosts) pointing to 127.0.0.1, and ensure localhost forwarding is enabled in your .wslconfig.

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

Because WSL2 runs inside a lightweight virtual machine with a dynamic NAT IP, understanding how Windows bridges loopback traffic is key to a frictionless development workflow.

The WSL2 Networking Challenge: NAT vs Loopback

Unlike WSL1 (which shared the exact network stack of Windows), WSL2 runs as a native Linux kernel in a managed Hyper-V utility VM.

Step 1: Configure .wslconfig for Localhost Forwarding

Windows includes a built-in proxy service that automatically forwards traffic from 127.0.0.1 on Windows to the active ports in WSL2.

Open or create your global WSL configuration file in Windows:

%USERPROFILE%\.wslconfig
(Example: C:\Users\YourUsername\.wslconfig)

Add the following configuration:

[wsl2]
localhostForwarding=true

# Optional for Windows 11 23H2 / 24H2 and newer:
# networkingMode=mirrored
# dnsTunneling=true

Restart WSL to apply the configuration:

# In Windows PowerShell (Admin)
wsl --shutdown

Step 2: Make Sure Your Dev Server Listens on 0.0.0.0

A frequent stumbling block: modern build tools (such as Vite, Next.js, Express or Django) often bind exclusively to 127.0.0.1 inside Linux. Because Windows connects through the virtual network interface, the server must listen on all interfaces (0.0.0.0).

Vite (`vite.config.ts`)

export default defineConfig({
  server: {
    host: '0.0.0.0', // or pass --host in package.json
    port: 3000,
  },
});

Next.js

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

Step 3: Add Custom Local Domains to Windows Hosts

Open your Windows hosts file with elevated administrator privileges:

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

Append your project domains:

# WSL2 Local Development Projects
127.0.0.1   myapp.test
127.0.0.1   api.myapp.test
127.0.0.1   admin.myapp.test

*(We recommend using the reserved .test TLD to avoid collisions with public top-level domains. See why .test is the safest local TLD.)*

Step 4: Flush DNS Cache

After saving the hosts file, flush the Windows DNS resolver cache:

# Windows PowerShell / Windows Terminal as Administrator
ipconfig /flushdns
Clear-DnsClientCache

Now open http://myapp.test:3000 in Chrome or Edge on Windows. Your requests will route directly to your dev server running inside WSL2.

How WSL2 Generates /etc/hosts Automatically

By default, WSL2 generates its internal /etc/hosts on startup by copying entries from the Windows hosts file.

This behavior is controlled inside WSL2 by /etc/wsl.conf:

# /etc/wsl.conf inside your WSL2 Linux distro
[network]
generateHosts = true
generateResolvConf = true

When generateHosts = true, every entry you add to your Windows hosts file is mirrored inside your Linux terminal. This means curl http://myapp.test:3000 works seamlessly both inside Windows and inside Linux.

Advanced: Modern Mirrored Networking Mode (Windows 11 24H2)

If you are running Windows 11 (build 22621+ or 24H2), Microsoft introduced Mirrored Networking Mode. This mode mirrors Windows network adapters directly into Linux, eliminating the NAT bridge completely.

In %USERPROFILE%\.wslconfig:

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

Benefits of Mirrored Mode:

• Zero NAT translation delays.
• Linux processes bind directly to 127.0.0.1 on Windows.
• Full VPN compatibility (Cisco AnyConnect, GlobalProtect).

Troubleshooting Common WSL2 Hosts Issues

1. Connection Refused on http://myapp.test

• Verify that your dev server is running and bound to 0.0.0.0.
• Check if another Windows process is already listening on the same port using netstat -ano | findstr :3000 in PowerShell.
• Read our guide on troubleshooting connection refused errors.

2. Browser Still Shows Old IP or Live Site

• Clear Chrome internal DNS cache at chrome://net-internals/#dns.
• Flush Windows DNS with ipconfig /flushdns.
• Check why hosts edits disappear or fail to take effect.

3. Docker Containers Inside WSL2

• When running Docker Engine directly in WSL2 (or via Docker Desktop WSL2 backend), use --add-host myapp.test:host-gateway or extra_hosts in docker-compose.yml to route traffic between containers and host services.
• Related: managing hosts entries with Docker.

Automating WSL2 and Windows Hosts with Sleezr

Juggling multiple client projects across WSL2, Docker, and native Windows tools can quickly make your hosts file messy.

Sleezr provides:

• Named environments (e.g., Client A, Staging, Microservices) that toggle with one click.
• Automatic DNS flush on every environment switch.
• Automatic hosts backup before every write operation.
• Full cross-platform support across Windows, macOS, and Linux.

Explore the complete Windows 11 hosts file guide or compare Sleezr vs PowerToys Hosts.

_Last tested: August 2026 on Windows 11 24H2 with WSL2 Ubuntu 24.04 LTS._

Sources and further reading

• Microsoft Learn: Advanced settings configuration in WSL
• Microsoft Learn: Accessing network applications with WSL
• RFC 6761: Special-Use Domain Names
• The hosts file explained (Wikipedia)