How to Configure WSL 2 Static IP Addressing in Windows 11 Using PowerShell

By default, the Windows Subsystem for Linux (WSL 2) employs dynamic Network Address Translation (NAT), assigning a new random internal IP address each time the virtual machine boots. For developers hosting local web services, running database containers, or binding development servers across testing devices on a local area network, changing IP addresses disrupts workflow scripts and firewall rules. Configuring persistent static IP addresses in Windows 11 provides reliable connectivity without recurring network reconfigurations.

Understanding WSL 2 Networking Modes in Windows 11

Windows 11 supports two distinct networking architectures for WSL 2:

• Mirrored Networking Mode: Maps host network interfaces directly into Linux, sharing the host’s IP address seamlessly. Configured via networkingMode=mirrored in .wslconfig.
• Static IP on NAT Virtual Switch: Retains isolated NAT containerization while binding fixed secondary IP addresses to both the Windows virtual adapter (vEthernet (WSL)) and the Linux eth0 interface.
• Bridge Networking (Hyper-V Switch): Exposes the Linux distribution directly to your local physical router with its own independent LAN IP address.

Method 1: Configuring Mirrored Networking (Recommended)

The simplest and cleanest method to achieve consistent network addressing is enabling Mirrored Networking, allowing Linux services to listen directly on localhost and your Windows machine’s physical IP:

1. Open PowerShell and navigate to your user profile directory:

   notepad "$env:USERPROFILE\.wslconfig"

2. Add or update the networking section:

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

3. Save the file and restart WSL 2 from an elevated terminal:

   wsl --shutdown

4. Launch your distribution. Services bound inside Linux are now immediately accessible on Windows using localhost:<port> and your local Windows IP address.

Method 2: Assigning a Fixed Static IP via Automated PowerShell Script

If your workflow requires an isolated, non-mirrored NAT subnet with a permanent fixed IP address (e.g., 192.168.50.2):

# Define the static IP configuration script
$scriptPath = "$env:USERPROFILE\Documents\Set-WSLStaticIP.ps1"

$scriptBody = @'
# Target static network parameters
$wslIP = "192.168.50.2"
$winIP = "192.168.50.1"
$subnetMask = "255.255.255.0"

# Assign secondary IP to Windows host vEthernet (WSL) adapter
try {
    New-NetIPAddress -InterfaceAlias "vEthernet (WSL)" -IPAddress $winIP -PrefixLength 24 -SkipAsSource $true -ErrorAction SilentlyContinue
} catch {}

# Assign static IP and gateway inside WSL 2 Linux distribution
wsl -u root -e ip addr add "$wslIP/24" broadcast 192.168.50.255 dev eth0
wsl -u root -e ip route add default via $winIP dev eth0 metric 100 2>$null

Write-Output "WSL Static IP successfully assigned: $wslIP"
'@

$scriptBody | Out-File -FilePath $scriptPath -Encoding utf8

Automating Static IP Assignment on System Boot

Because WSL 2 recreates internal network interfaces when starting, register a scheduled task to run this script whenever you log in:

# Create scheduled task running with administrative privileges
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-WindowStyle Hidden -ExecutionPolicy Bypass -File `"$env:USERPROFILE\Documents\Set-WSLStaticIP.ps1`""
$trigger = New-ScheduledTaskTrigger -AtLogOn
$principal = New-ScheduledTaskPrincipal -UserId "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel Highest

Register-ScheduledTask -TaskName "WSL_Static_IP_Init" -Action $action -Trigger $trigger -Principal $principal -Description "Assigns persistent static IP to WSL 2."

Verifying Network Connectivity and Ping Tests

Confirm bidirectional network communication between host and guest:

1. From Windows PowerShell, ping the assigned Linux static IP:

   Test-Connection -TargetName 192.168.50.2 -Count 2

2. From inside your WSL distribution, verify the configured interface address:

   ip addr show dev eth0

With this setup, all development endpoints, database connections, and test scripts maintain uninterrupted communication without requiring periodic manual IP adjustments.