wsl-vpnkit Documentation

Download wsl-vpnkit.wsl from the latest release and open it to import the distro into WSL 2. This method works without needing existing network connectivity in WSL.

To start the service in the foreground, use:

wsl.exe -d wsl-vpnkit --cd /app wsl-vpnkit

To update the wsl-vpnkit distro, unregister the existing one and import a new wsl-vpnkit.wsl file.

wsl.exe --unregister wsl-vpnkit

You can install wsl-vpnkit as a script within an existing distro (e.g., Ubuntu). This involves installing dependencies, downloading the binaries, and setting up a systemd service.

# install dependencies
sudo apt-get install iproute2 iptables iputils-ping dnsutils wget jq

# download wsl-vpnkit and unpack
wget https://github.com/sakai135/wsl-vpnkit/releases/latest/download/wsl-vpnkit-amd64.wsl -O wsl-vpnkit.wsl
tar --strip-components=1 -xf wsl-vpnkit.wsl app/wsl-vpnkit app/wsl-gvproxy.exe app/wsl-vm app/wsl-vpnkit.service
rm wsl-vpnkit.wsl
sudo mv wsl-vpnkit wsl-gvproxy.exe wsl-vm /usr/local/bin/

# run the wsl-vpnkit script in the foreground
sudo wsl-vpnkit

# setup systemd
sudo mv ./wsl-vpnkit.service /etc/systemd/system/
sudo systemctl enable wsl-vpnkit
sudo systemctl start wsl-vpnkit
systemctl status wsl-vpnkit

To have wsl-vpnkit.service start automatically with your distro, copy the service file from the wsl-vpnkit distro to your primary distro and enable it via systemctl.

# copy the service file from wsl-vpnkit to your distro
wsl.exe -d wsl-vpnkit --cd /app cat /app/wsl-vpnkit.service | sudo tee /etc/systemd/system/wsl-vpnkit.service

sudo systemctl enable wsl-vpnkit
sudo systemctl start wsl-vpnkit
systemctl status wsl-vpnkit

If networking issues persist, you can reset the state by shutting down WSL and killing any remaining wsl-gvproxy processes.

# PowerShell

# shutdown WSL to reset networking state
wsl --shutdown

# kill any straggler wsl-gvproxy processes
kill -Name wsl-gvproxy

If your WSL release is older than 2.4.4, you must use the manual --import command in PowerShell. Replace wsl-vpnkit.wsl with the path to your downloaded file.

# PowerShell

wsl --import wsl-vpnkit "$env:USERPROFILE\wsl-vpnkit" wsl-vpnkit.wsl --version 2

wsl-vpnkit uses /mnt/wsl/resolv.conf to find the WSL 2 gateway IP. If you have modified /etc/resolv.conf with custom DNS, you must set generateResolvConf=false in your wsl.conf.

For older WSL versions where /mnt/wsl/resolv.conf is unavailable, you must manually set the WSL2_GATEWAY_IP environment variable.

If you encounter cannot execute binary file: Exec format error, the WSL interop configuration might be missing. You can regenerate the interop configuration with the following commands:

sudo sh -c 'echo :WSLInterop:M::MZ::/init:PF > /usr/lib/binfmt.d/WSLInterop.conf'
sudo systemctl restart systemd-binfmt

If Windows security prevents running executables from certain directories, move wsl-gvproxy.exe to an allowed location and use the GVPROXY_PATH environment variable.

# enable [automount] in wsl.conf for wsl-vpnkit distro
wsl.exe -d wsl-vpnkit --cd /app sed -i -- "s/enabled=false/enabled=true/" /etc/wsl.conf

# set GVPROXY_PATH when running wsl-vpnkit
wsl.exe -d wsl-vpnkit --cd /app GVPROXY_PATH=/mnt/c/path/wsl-gvproxy.exe wsl-vpnkit

To troubleshoot issues, run the wsl-vpnkit command with the DEBUG=1 environment variable set.

# set the DEBUG environment variable
wsl.exe -d wsl-vpnkit --cd /app DEBUG=1 wsl-vpnkit