Configuring Port Forwarding with WSL2 and IP Passthrough

To enable external devices to access services running in WSL2, you must configure Hyper-V IP Passthrough. This feature assigns a unique physical IP address to the WSL2 virtual switch, bypassing NAT and allowing direct connectivity from your local network without manual port forwarding rules.

Understanding the Networking Limitation

By default, WSL2 runs inside a lightweight utility VM managed by Hyper-V. This VM is connected to an internal virtual switch that uses Network Address Translation (NAT). While this allows the Windows host to reach the Linux guest via localhost, it prevents other devices on your LAN from initiating connections to the WSL2 instance. The standard workaround involves complex PowerShell scripts to add netsh port proxy rules, but these are fragile and break when the dynamic IP of the WSL2 interface changes. The robust solution is to use Hyper-V's IP Passthrough mode. This feature, available in Windows 10 version 2004 and later, allows the WSL2 VM to obtain its own IP address directly from your DHCP server or through static configuration. Once configured, the WSL2 instance appears as a distinct device on your network, just like any other computer connected to your router. For more details on how Hyper-V handles network isolation, see Hyper-V: Accessing LAN Devices on Host.

Prerequisites and Verification

Before modifying network settings, ensure your system meets the requirements. You need Windows 10 Build 19041 or higher, or Windows 11. Additionally, you must have administrative privileges to modify Hyper-V settings. First, verify that the WSL2 virtual switch exists. Open PowerShell as Administrator and run:

Get-VMNetworkAdapter -ManagementOS | Select-Object Name, SwitchName

You should see an entry named "vEthernet (WSL)". Note the name of the management OS network adapter, as you will need it for the next steps. If you do not see this adapter, ensure WSL2 is installed and running by executing wsl --update and restarting your machine. It is also helpful to check the current state of your firewall. Ensure that inbound rules for the specific ports you intend to expose (such as HTTP port 80 or HTTPS port 443) are enabled in Windows Defender Firewall. Without these rules, even with correct networking, external requests will be dropped.

Configuring IP Passthrough

The core of this configuration involves enabling passthrough on the WSL2 virtual network adapter. This tells Hyper-V to allow traffic destined for the adapter to pass directly to the WSL2 VM rather than being translated by the host. Run the following command in an elevated PowerShell terminal:

Set-VMNetworkAdapter -ManagementOS -Name "vEthernet (WSL)" -IPPassThroughEnabled $true

If the command executes successfully, it returns no output. To verify the setting, run:

Get-VMNetworkAdapter -ManagementOS -Name "vEthernet (WSL)" | Select-Object IPPassThroughEnabled

The output should show $true. At this stage, the infrastructure is ready, but the WSL2 VM still needs an IP address. Since it is no longer behind NAT, it may not receive one automatically if your router does not support DHCP relay for virtual switches.

Assigning a Static IP to WSL2

With IP passthrough enabled, the most reliable method to ensure consistent connectivity is to assign a static IP address to the WSL2 instance. This avoids issues where the IP changes after every restart. Inside your WSL2 distribution (e.g., Ubuntu), edit the Netplan configuration file. For newer Ubuntu versions using Netplan, locate the file in /etc/netplan/. It might be named 50-cloud-init.yaml or similar. Open the file with a text editor:

sudo nano /etc/netplan/50-cloud-init.yaml

Modify the network configuration to include a static address. Replace the values below with an IP address that falls within your subnet but is outside your DHCP pool to avoid conflicts. For example, if your network is 192.168.1.x and your router is 192.168.1.1, you might choose 192.168.1.150.

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.1.150/24
      nameservers:
        addresses:
          - 8.8.8.8
          - 1.1.1.1
      routes:
        - to: default
          via: 192.168.1.1

After saving the file, apply the changes:

sudo netplan apply

Your WSL2 instance now has a fixed IP address. You can verify it by running ip addr inside WSL2. The interface eth0 should display the new static IP.

Testing External Connectivity

Now that the network is configured, test the connection from another device on your LAN. Open a browser or use curl on a different computer and navigate to http://192.168.1.150:80 (or whatever port your service listens on). If the connection fails, check two things: 1. Firewall: Ensure Windows Firewall is not blocking the incoming connection on the specific port. You may need to create an inbound rule in Windows Defender Firewall Advanced Settings. 2. Service Binding: Ensure your web server inside WSL2 is binding to 0.0.0.0 rather than 127.0.0.1. Binding to localhost only accepts connections from within the VM. For related troubleshooting on WSL2 networking quirks, refer to WSL2: Localhost:8888 Stopped Working - Fixing the Issue.

Frequently Asked Questions

Does IP Passthrough work with Docker Desktop?

No, IP Passthrough is specific to the native WSL2 backend. Docker Desktop uses its own Hyper-V VM and networking stack, which requires separate configuration via Docker's network settings or bridge adapters. Mixing these configurations can lead to unpredictable behavior.

What happens to my WSL2 IP after a reboot?

If you have configured a static IP in Netplan as described above, the address will remain constant across reboots. However, if you rely on DHCP, the address may change. Always prefer static assignment for server-like scenarios to maintain stable remote access.

Can I use IPv6 with this setup?

Yes, WSL2 supports IPv6. You can configure IPv6 addresses in your Netplan YAML file similarly to IPv4. Ensure your router and network infrastructure support IPv6 routing to the WSL2 virtual switch for external devices to reach it.

Why can't I ping my WSL2 IP from the host?

Ping may be blocked by ICMP filtering rules in Windows Firewall or within the Linux kernel itself. By default, some distributions drop ICMP echo requests. Check your firewall rules and ensure ICMP is allowed if you need to troubleshoot connectivity.

Is there a risk of IP conflict?

Yes, if you manually assign an IP that is already in use by another device on your network. Always choose an IP outside your router's DHCP range to prevent conflicts. Consult your router's admin panel to determine the DHCP pool boundaries.