WSL hostAddressLoopback: Reach Assigned Windows IPv4 Addresses in Mirrored Mode

Mirrored networking already supports a localhost path between Windows and WSL for common development workflows. The experimental hostAddressLoopback setting addresses a different case: it allows a container or WSL environment to connect to the Windows host, or the host to connect to WSL, using an IPv4 address assigned to the host rather than only 127.0.0.1. It is easy to misread that as a way to expose an application to every network peer. The documented scope is host/guest communication over host-assigned IPv4 addresses; it does not replace listener binding, firewall policy, routing, or service health checks.

Scope, prerequisites, and exact behavior

Microsoft documents hostAddressLoopback under [experimental]. It applies only when [wsl2] networkingMode=mirrored, is available only on Windows 11, and requires Windows 11 version 22H2 or higher according to the current .wslconfig reference. The default is false. When set to true, the documentation says the container can connect to the host, or the host to the container, by an IP address assigned to the host. IPv4 host addresses are supported; the docs explicitly distinguish this from the 127.0.0.1 loopback address, which can always be used.

Keep three address cases separate:

127.0.0.1 is the IPv4 loopback interface in the network namespace where the client runs. WSL’s documented localhost behavior is its own integration path.
An IPv4 address assigned to a Windows host interface is a host address, such as the address on a VPN or local adapter. hostAddressLoopback is about using such host-assigned addresses for host/WSL communication.
A LAN peer connecting to a Windows or WSL service is a separate inbound network path involving routes, listen addresses, and firewall rules.

An address that works from the guest does not prove it is reachable from a remote laptop. Conversely, a service listening only on loopback may not accept a connection addressed to another host interface. Test the actual bind address and client location.

Define the exact connection before changing the setting

Write down the client and server directions. Is Windows connecting to a WSL process at a Windows-assigned IP, or is Linux connecting to a service on Windows at that address? Which adapter owns the address: Ethernet, Wi-Fi, VPN, loopback alias, or a virtual adapter? What port and protocol are required? Does the app listen on 127.0.0.1, a specific IPv4 address, or a wildcard?

Capture the Windows address inventory and Linux interfaces/routes before editing. In PowerShell, Get-NetIPAddress -AddressFamily IPv4 helps identify addresses assigned to Windows interfaces. In WSL, record ip -4 address, ip route, and the active mode if the installed WSL supports wslinfo --networking-mode. These commands describe state; they do not prove that a firewall permits a connection.

Then test the existing localhost path. If 127.0.0.1 already reaches the service, enabling an experimental additional-address path may add no value. If localhost fails, first confirm the mode and service’s listening address. A failed local connection could be an application binding problem rather than an address translation feature.

Configure only the address path that needs testing

The configuration shape is:

[wsl2]
networkingMode=mirrored

[experimental]
hostAddressLoopback=true

Both settings are global to WSL 2 for the Windows account. The advanced option is experimental and should be validated on the precise Windows/WSL release intended for use. Keep the existing configuration, record a backup, and avoid changing DNS, Hyper-V firewall, port collision, or proxy settings in the same test.

Apply the global change only after stopping stateful workloads. A full WSL shutdown forces a VM restart but ends all running WSL distributions. Start the target distro, re-check its route/interface state, and use one known Windows-assigned IPv4 address as the test target. Do not hard-code an address that a DHCP server or VPN can change. If this is a repeatable development setup, make the test discover the address from the Windows host rather than silently relying on an old value.

Verify service binding and each direction separately

For a Windows service that Linux should reach, check the Windows-side listening address and firewall policy first. A process bound only to Windows loopback may behave differently from one bound to a host interface. Do not broaden an application’s bind address without understanding which clients that exposes it to. Then from WSL, test the exact Windows-assigned IPv4 address and port using a client appropriate for the protocol, and record whether failure is immediate refusal, timeout, or name-resolution error.

For a WSL service that Windows should reach, inspect the guest’s listener:

sudo ss -lntup

Run the request from Windows to the specific host-assigned address and port; separately run a request from the WSL guest itself. A guest-local success plus a Windows-host failure narrows the problem to the host/guest path, binding, or filtering layer. It does not justify changing the Windows firewall automatically. If the application is bound only to 127.0.0.1 inside Linux, evaluate whether that binding is compatible with the documented address path before adding broad wildcard binding.

Test one direction at a time. A successful Linux-to-Windows TCP connection does not prove Windows-to-Linux is working, and a successful IPv4 test says nothing about IPv6. Microsoft documents only IPv4 assigned host addresses for this setting. Record the exact source/destination tuple, protocol, adapter, WSL mode, and result.

Separate host loopback from firewall and LAN exposure

Mirrored mode integrates WSL networking with host interfaces, and Windows Firewall plus Hyper-V firewall policy may filter traffic. hostAddressLoopback is not an allow rule. If a packet reaches a firewall and is rejected, the configuration option does not override that policy. Follow the Microsoft Hyper-V firewall documentation and organizational policy for inbound rules, using the narrowest source, port, protocol, and direction that satisfies the use case.

Do not use an internet-facing or LAN device as the first test. Start with the Windows host and one WSL distro on a controlled port. Then, only if the service must be available to other devices, test from an authorized second host and configure the appropriate firewall and application access controls independently. A host-assigned address can belong to a VPN or an interface with a different trust boundary from the local LAN.

Names can also confuse the diagnosis. If localhost works but a host-address request fails, DNS is not involved when you use a numeric address; inspect route, bind, and filter behavior. If a hostname fails but a numeric address succeeds, troubleshoot name resolution separately. Avoid conflating this setting with DNS tunneling or /etc/hosts.

Acceptance, observability, and rollback

An acceptance matrix should list each required path with client, destination IP, port, protocol, service process, expected result, and observed result. Include the baseline localhost path, the new host-address path, the reverse direction if required, and a negative test from an unauthorized network peer where exposure is a concern. Confirm application logs and host/guest listener state instead of relying only on ping, which does not test a TCP service and may be filtered.

If the additional path is unavailable after restart, confirm Windows and WSL versions, that mirrored mode is actually active, that the target address belongs to the Windows host, and that the service is listening on a compatible address. Check firewall counters or logs where permitted. Remove hostAddressLoopback=true if it does not solve the verified use case; do not leave experimental global configuration simply because it caused no obvious error.

Document the reason, assigned address class, target service, approved client direction, Windows build, WSL package version, and rollback date. Re-test after a WSL or VPN update because address assignments and policy can change independently. The feature is useful when a specific local host/guest path requires a host interface address; it is not a generic switch that makes WSL reachable from everywhere.

Related:

Sources: