WSL Mirrored Networking ignoredPorts: Resolve Host-Port Collisions Precisely

Mirrored networking lets WSL 2 share aspects of the Windows host’s network configuration, but it also creates port-binding interactions that are different from the older NAT model. The experimental ignoredPorts setting lets Linux applications bind selected ports even when Windows is already using those ports, for Linux-internal traffic. It is not a firewall allow rule, a port-forward, or a way to expose a service to another machine. The correct decision depends on whether the collision is real, which side owns the listener, and whether the intended clients live inside Linux, on Windows, or elsewhere on the network.

What the documented feature does

Microsoft’s current .wslconfig reference says ignoredPorts is an experimental comma-separated list, only applicable when [wsl2] networkingMode=mirrored. It enables a Linux application to bind to a port that is already used in Windows, so the Linux listener can be used for traffic within Linux. The documentation’s example is port 53 for Docker Desktop listening to requests from a Linux container. This is a deliberate coexistence exception, not a general route for every connection that would otherwise fail.

The setting does not make two independent applications share one TCP socket. It does not merge their listening queues, choose the right process for each client, or ensure that packets from Windows or a LAN peer reach the Linux listener. It controls whether Linux can bind to a port that the host is using. Traffic scope and firewall policy remain separate questions.

The current documentation marks this key as Windows 11-only and requires Windows 11 version 22H2 or higher. It remains in [experimental], so verify the installed WSL version and current settings table before deploying it. An older package can reject or ignore a setting that a current online page documents.

Diagnose the collision before adding an exception

Start with the process that owns the port on each side. On Windows, use the appropriate PowerShell network or process inspection commands and record the executable, protocol, and bind address. In WSL, inspect listeners with:

sudo ss -lntup
sudo ss -lnup

TCP and UDP have separate port spaces; a UDP DNS listener and a TCP listener on the same numeric port are not automatically the same conflict. A process bound only to 127.0.0.1 is also different from one bound to a wildcard address. Record protocol, address, process, and the clients that need to reach it before changing configuration.

Check that mirrored networking is active and that the problem is genuinely a bind failure. A service that starts but cannot be reached might instead have an application-level bind address, Hyper-V firewall policy, Windows firewall policy, VPN route, or client DNS issue. Inspect service logs and the application’s actual listen address. Do not add ignoredPorts to solve a blocked LAN connection when the application already binds successfully.

Confirm whether the desired connection is Linux-to-Linux, Windows-to-WSL, or from another LAN host. The setting is specifically described for Linux-only traffic in the example behavior. If a Windows client should connect to a WSL service, evaluate mirrored networking’s documented host/guest path and firewall requirements instead. If a remote device should connect, validate the host’s inbound firewall policy and the exact service binding separately.

Configure a narrow list

An illustrative configuration for two intentional Linux-side collisions is:

[wsl2]
networkingMode=mirrored

[experimental]
ignoredPorts=53,3000

Do not copy this list as a standard. Include only ports for which a confirmed Windows listener must coexist with a Linux listener. Avoid adding broad or undocumented syntax such as ranges, protocol suffixes, or wildcard entries; the current Microsoft example specifies comma-separated numeric ports. Preserve all existing .wslconfig settings and keep the option in the experimental section.

This is a global WSL 2 setting rather than a per-distro allow-list. A port exception can therefore affect multiple distributions sharing the VM. Before rollout, identify each distro or container that might bind the listed port and assign an owner. A port used by DNS in a container environment, for example, can have a different purpose from a developer’s local HTTP server. Document the intended listener and the clients expected to use it.

Apply the change and test each path independently

Changes to .wslconfig are read at WSL startup. Stop affected services cleanly and perform a full shutdown if a clean VM-level test is required:

wsl.exe --list --running
# Stop containers and other stateful services first.
wsl.exe --shutdown

Restart the relevant distro and confirm its networking mode using the installed WSL’s supported introspection or documented behavior. Launch the Windows listener first, then test whether Linux can bind the intended protocol and port. Record the Linux listener’s actual address with ss. Next, test the exact intended Linux client. Finally, test Windows or LAN clients only if they are part of the requirement; do not infer their behavior from Linux’s successful bind.

If the Linux bind still fails, check for a second Linux process, address-family differences, an incorrect port, unsupported WSL build, wrong config location, or failure to restart the VM. If the bind succeeds but the client cannot connect, trace that path separately. ignoredPorts does not disable Windows Defender Firewall, Hyper-V firewall rules, Linux firewall rules, or application authorization. It is not an inbound firewall exception.

Acceptance should include the negative case too: verify that a port not listed in ignoredPorts continues to behave according to the normal mirrored-mode binding rules on the target build. Verify Windows’ original listener still accepts its intended Windows-side clients. Confirm the Linux application is restricted to its intended guest-side clients and has not been accidentally bound broadly by an unrelated setting.

Operational pitfalls

Do not treat the configuration as a reservation. If the Windows application stops listening, the ignored-port entry may remain but no longer serve a useful purpose. Periodically review the list against the running service inventory. Port ownership changes after software updates, and a stale exception makes later debugging harder.

Avoid adding the same port to multiple ad hoc lists in scripts and GUI-managed configuration. Keep one authoritative .wslconfig, note which administrator owns it, and verify that WSL Settings still displays the expected values if the application is used to edit the file. A saved string is not effective-state proof; test the bind behavior after restart.

The feature’s “ignored” name can invite an overbroad interpretation. It does not mean WSL ignores packets, ignores firewall policy, or ignores all Windows port use. It describes an exception to Linux binding when Windows is using the port. Keep that distinction explicit in documentation and change reviews, especially when a service’s exposure has operational consequences.

Also distinguish a socket bind collision from application-level port sharing. If the Linux process uses SO_REUSEPORT or SO_REUSEADDR, those are socket options with their own Linux semantics; they do not make a Windows process and a Linux process share one application socket. ignoredPorts is a WSL networking exception, not a cross-platform load balancer. Avoid configuring both mechanisms until you can explain which one is required and how the clients select the intended endpoint.

When a container runtime is involved, inspect both the workload container’s published ports and the Linux host namespace. A successful bind inside one container does not prove the service is published to the WSL host, and a port exception does not create a Docker or Podman port-publishing rule. Test from the intended client namespace. Include the runtime configuration in the record, but do not broaden host firewall access merely to make a container-to-container path work.

For repeatable acceptance, keep the Windows process alive during the Linux bind test and note its exact local address. Stop it and repeat only if the intended design should allow Linux to own the port when Windows releases it. Avoid parallel tests that reuse the same port: they make it impossible to tell whether the allowed bind came from the option, a process exit, or a different address family. A narrow sequential test gives a trustworthy result without changing unrelated networking controls.

Rollback and change record

If the exception creates unexpected behavior, remove only the affected port from ignoredPorts, preserve other global settings, shut down WSL, and repeat the same bind/client matrix. Do not toggle firewall rules to compensate unless evidence independently shows a firewall block. The rollback record should contain WSL and Windows versions, the port and protocol, Windows owner process, Linux listener, intended client path, before/after results, and why the exception was retained.

The change is production-ready only when the original collision is reproducible, the Linux listener binds with the narrow list, Windows retains its own intended listener behavior, the right clients can reach the right service, unrelated ports remain unchanged, and the list has a named owner. Anything less risks turning a port-collision workaround into an undocumented networking assumption.

Related:

Sources: