Windows WSL Guide: Setup Developer Linux build system with Windows Subsystem Linux (WSL2)#

This guide explains how to prepare a Windows machine using Windows Subsystem for Linux 2 (WSL2) with Ubuntu 24.04.

Prerequisites#

Windows 11
Administrator access on the Windows machine

Step 1: Install WSL2 with Ubuntu 24.04#

Open PowerShell as Administrator and run:

wsl.exe --install Ubuntu-24.04

This installs WSL2 and Ubuntu 24.04 in one step. Reboot if prompted.

For full WSL command reference, see: https://learn.microsoft.com/en-us/windows/wsl/basic-commands

Step 2: Launch Ubuntu 24.04#

wsl.exe -d Ubuntu-24.04

This opens a Ubuntu 24.04 terminal. All subsequent steps run inside this terminal.

Step 3: Network configuration#

Depending on the Windows development system’s network connectivity, the networking settings must be configured accordingly.

3.1: The Windows development system is connected to a lab network via a proxy server (no VPN).#

3.1.1: Configure proxy environment variables according to your network setup.#

Note: Use “” if the proxy is not required in your network for all the proxy environment variables.

# Append the proxy environment variables to /etc/environment
http_proxy="http://proxy-server-ip:port"
https_proxy="http://proxy-server-ip:port"
no_proxy=".internal,127.0.0.1,::1,localhost"
HTTP_PROXY="http://proxy-server-ip:port"
HTTPS_PROXY="http://proxy-server-ip:port"
NO_PROXY=".internal,127.0.0.1,::1,localhost"

# Append the following lines to ~/.bashrc
export PATH=$PATH:/usr/local/go/bin
export http_proxy="http://proxy-server-ip:port"
export https_proxy="http://proxy-server-ip:port"
export no_proxy=".internal,127.0.0.1,::1,localhost"
export HTTP_PROXY="http://proxy-server-ip:port"
export HTTPS_PROXY="http://proxy-server-ip:port"
export NO_PROXY=".internal,127.0.0.1,::1,localhost"

# Configure apt proxy variables according to your network setup /etc/apt/apt.conf.d/apt.conf
Acquire::http::proxy "http://proxy-server-ip:port";
Acquire::https::proxy "http://proxy-server-ip:port";

3.2: The system is connected through a VPN (automated proxy using mirrored mode).#

If you are on VPN and WSL2 cannot connect to the internet (e.g., apt update fails or proxy is unreachable), enable mirrored networking mode.

This makes WSL2 share Windows’ network stack directly so VPN routing applies to WSL2 too.

3.2.1: Open `.wslconfig` in Notepad#

In Windows PowerShell (not inside WSL):

notepad "$env:USERPROFILE\.wslconfig"

3.2.2: Add the following configuration#

[wsl2]
networkingMode=mirrored

Save and close Notepad.

3.3 Restart WSL#

wsl --shutdown
wsl -d Ubuntu-24.04

3.4 Verify connectivity#

Inside the Ubuntu 24.04 terminal:

curl -I http://archive.ubuntu.com
sudo apt update
sudo apt upgrade -y

# Install go lang and tools required for build
wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz
sudo apt install -y make

Step 4: Clone the Repository and Build Artifacts#

The build steps are the same on WSL2 as on a native Linux developer system. From inside the Ubuntu 24.04 terminal, follow Phase 1 — Build Artifacts on the Developer System in the Build from Source guide to clone the repository and run make build MODE=image-from-iso ....

Once the build completes and you have usb-installation-files.tar.gz, continue with Step 5 below to attach your USB drive to WSL2.

Step 5: Attach USB Drive to WSL2#

To run bootable-usb-prepare.sh inside WSL2, the USB drive must be explicitly attached using usbipd-win.

5a. Install usbipd-win on Windows#

In Windows PowerShell as Administrator:

winget install usbipd

Alternatively, download the installer from: https://github.com/dorssel/usbipd-win/releases

5b. List available USB devices#

In Windows PowerShell as Administrator:

usbipd list

Example output:

BUSID  VID:PID    DEVICE                                                        STATE
1-13   2174:2100  USB Attached SCSI (UAS) Mass Storage Device                   Not shared

5c. Bind the USB device (one-time setup per device)#

usbipd bind -f -b 1-13

Replace 1-13 with the BUSID of your USB drive from the list above.

5d. Attach the USB device to WSL2#

usbipd attach -w -b 1-13

The device state will change to Attached:

BUSID  VID:PID    DEVICE                                                        STATE
1-13   2174:2100  USB Attached SCSI (UAS) Mass Storage Device                   Attached

5e. Verify the device is visible in WSL2#