localhost vs 127.0.0.1 in Windows WSL2

Why can a frontend service running on Windows not access a backend API running in WSL2 via http://127.0.0.1, but can access it normally via http://localhost?

The root cause is that localhost and 127.0.0.1 point to different targets in WSL2’s network architecture. On Windows, localhost is a hostname for which WSL2 configures a special forwarding mechanism; whereas 127.0.0.1 is a fixed IPv4 loopback address, and under WSL2’s default network mode, it points inside the WSL2 virtual machine, not to the Windows host.

🏗️ Root cause: WSL2 is an independent virtual machine

WSL2 is not a traditional compatibility layer, but a lightweight virtual machine with its own independent network stack and IP address. This means:

• Inside WSL2, 127.0.0.1 points to WSL2’s own loopback interface.
  
• When a frontend service running on Windows makes a request via http://127.0.0.1, the request is sent to Windows’ own loopback address, but the backend service is actually listening inside the WSL2 virtual machine’s network namespace. The two are not interconnected.
  

⚙️ Key mechanism: forwarding and resolution differences for localhost

localhost works because WSL2 provides a dedicated forwarding mechanism, and localhost’s resolution behavior differs from that of 127.0.0.1.

• Port forwarding for localhost: In the default NAT network mode, WSL2 runs a Linux process named localhost. This process monitors TCP ports bound in WSL2 and forwards traffic to Windows through wslrelay.exe. Meanwhile, the localhostForwarding setting on the Windows side (enabled by default) also ensures that requests made via localhost can be forwarded to WSL2.
  
• IPv6-priority resolution: This is another common reason why 127.0.0.1 fails. When you enter http://localhost in a browser, the system prioritizes resolving localhost to the IPv6 ::1 address. WSL2’s forwarding mechanism can usually handle this IPv6 connection correctly. But when you explicitly use http://127.0.0.1, you force the use of the IPv4 loopback address, which has no corresponding listening port on the Windows host, so the connection fails.
  

💡 Solutions

Depending on your Windows version and specific needs, you can choose one of the following:

• Recommended: use localhost (easiest)
  In the Windows frontend service, simply configure the backend API address as http://localhost:. This is the simplest method and requires no extra configuration, fully leveraging WSL2’s built-in forwarding mechanism.
• Upgrade option: enable mirrored networking mode (Windows 11 22H2+)
  If your system supports it, this is a more thorough solution. Mirrored mode lets Windows and WSL2 share the network stack, making localhost interoperable in both directions, and 127.0.0.1 usually works as well.
  1. Create or edit the .wslconfig file in your Windows user directory (e.g., C:\Users\YourUserName\).
     
  2. Add the following:
     ini [wsl2] networkingMode=mirrored
     3. Run wsl --shutdown in PowerShell to restart WSL.
     
• Long-term option: adjust the service binding address
  In WSL2, bind your backend service to 0.0.0.0 instead of 127.0.0.1. This makes the service listen on all network interfaces, so it can be accessed by requests from the Windows virtual NIC. However, note that this may expose the service to the LAN, so be cautious in production environments.

💎 Summary

In short, localhost works because WSL2 establishes a “dedicated channel” from Windows to WSL2; 127.0.0.1 does not work because it sends requests to Windows’ own “local loopback” rather than to the WSL2 virtual machine. Therefore, when accessing services in WSL2 from Windows, using localhost first is the most direct and effective method.