Skip to main content
Windows Subsystem for Linux (WSL) is a Windows feature that runs Linux distributions on Windows without using virtualization software. WSL allows a Linux user space to operate concurrently with Windows applications on the same host, eliminating the requirement for a separate virtual machine. The following figure shows the tasks involved in setting up WSL and installing Ubuntu:
verify Windows host system requirements, enable WSL and install Ubuntu, and configure Ubuntu settings in WSL

​
Verify Windows host system requirements

The following table lists the minimum hardware resources the WSL environment needs for Qualcomm Linux builds:
RequirementSpecification
Processor architectureX64
CPU cores8 or more
RAM16 GB or more
Storage400 GB of free space

​
Enable WSL and install Ubuntu

Qualcomm Linux uses the Ubuntu 22.04 Linux distribution. The steps to enable WSL and install Ubuntu differ based on your Windows version. Follow the instructions applicable to your version:
For instructions on how to enable WSL 2 and install Ubuntu 22.04, see Install Ubuntu on WSL 2.

​
Configure Ubuntu settings in WSL

To set up the WSL environment, configure WSL-specific settings in WSL. Use the wsl.conf file to configure the following WSL-specific settings for the Linux distro you installed:
  • [automount] options = "metadata": Enables Linux-style file permissions
  • [boot] systemd = true: Enables systemd in WSL
  • [boot] command = systemctl start docker: Starts the Docker service automatically when WSL launches
WSL automatically applies the settings in the wsl.conf file every time you open it. To configure WSL-specific settings, do the following:
  1. In the Ubuntu terminal, use the sudo command to add the following contents in the /etc/wsl.conf file:
    /etc/wsl.conf
    [automount]
options = "metadata"

[boot]
systemd=true
command = systemctl start docker
  2. In Windows PowerShell, run the following command to restart WSL:
    PowerShell
    wsl --shutdown

​
Enable USB device access for WSL

WSL 2 runs in a lightweight VM that doesn’t have access to USB devices by default. As a result, commands such as lsusb and flashing tools can’t detect the target device. To enable USB access for WSL, use usbipd-win to pass the USB device’s traffic from Windows to WSL using USB/IP:
  1. Open Windows PowerShell as administrator and run the following command to install usbipd-win:
    PowerShell
    winget install --interactive --exact dorssel.usbipd-win
  2. Optional: To enable mirrored networking, in Windows PowerShell, run the following command to create the .wslconfig file in your user profile:
    PowerShell
    @"
[wsl2]
networkingMode=mirrored
"@ | Set-Content -Encoding ASCII $env:USERPROFILE\.wslconfig
    On corporate or Group Policy–managed machines, the default network address translation (NAT) networking mode may block the firewall rule that usbipd requires, causing the device attach to fail. Switching to mirrored networking routes the connection over loopback, bypassing the restriction.
    Name the file exactly .wslconfig, not .wslconfig.txt. Notepad can append a .txt extension. Hence, use Windows PowerShell to create the file and apply the correct extension.
  3. To restart WSL, run the following command:
    PowerShell
    wsl --shutdown
  4. In the Ubuntu terminal, run the following command to install the USB/IP client tools:
    Ubuntu terminal
    sudo apt update
sudo apt install -y linux-tools-virtual hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip "$(ls /usr/lib/linux-tools/*/usbip | tail -n1)" 20
  5. Open Windows PowerShell as administrator and run the following command to list the connected USB devices:
    PowerShell
    usbipd list
  6. Make a note of the BUSID of the device you want to flash. For flashing Qualcomm devices, BUSID is typically the QDLoader 9008 device (05c6:9008, EDL mode) or the Fastboot device.
    Sample output
    BUSID  VID:PID    DEVICE                                STATE
1-4    05c6:9008  Qualcomm HS-USB QDLoader 9008         Not shared
2-1    18d1:4ee7  Android / Fastboot device             Not shared
  7. Open Windows PowerShell as administrator and run the following command to bind the device once:
    PowerShell
    usbipd bind --busid 1-4
Binding persists across reboots, so you only need to do it once per device.
  1. Replace 1-4 with your actual BUSID. The device’s STATE changes to Shared.
  2. In Windows PowerShell, run the following command to attach the device to WSL:
    PowerShell
    usbipd attach --wsl --busid 1-4
    • Re-attach after every replug or mode switch: When a device changes modes during flashing (for example, normal → EDL 9008, or → fastboot), Windows re-enumerates it, often with a new BUSID and the WSL attachment drops. Re-run usbipd list and then run usbipd attach --wsl --busid <new-busid>. This is a common source of errors when flashing Qualcomm devices in WSL.
    • Re-attach after every WSL restart: The attachment doesn’t persist across wsl --shutdown or a system reboot; only the bind persists.
  3. In the Ubuntu terminal, run the following command to confirm that Ubuntu detects the device:
    Ubuntu terminal
    lsusb
    The device must appear in the list, for example, as follows: 
    Bus 001 Device 002: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
    The flashing tool running inside WSL can now detect the device. For flashing instructions, see Qualcomm Linux Build Guide.
  4. To detach the device after flashing, run the following command in Windows PowerShell:
    PowerShell
    usbipd detach --busid 1-4

​
Troubleshoot WSL issues

Resolve common issues related to performance, disk space, domain name system (DNS), build errors, and USB pass-through that may occur when using WSL for Qualcomm Linux builds.

​
Performance issues in WSL

If you’re experiencing performance issues in WSL, tune global resource limits, such as memory, CPU, and swap using the .wslconfig file. The resource limits apply to all WSL 2 distributions. Adjust settings incrementally and validate results after each change. For more information, see Advanced settings configuration in WSL.
Don’t configure the memory and CPU values to mirror the host specifications. Excessive allocation may decrease stability and adversely affect Windows performance.

​
Insufficient disk space on the C drive for Qualcomm Linux builds

By default, Ubuntu installs on the C drive. If the C drive doesn’t have enough free space for Qualcomm Linux builds, move the Ubuntu installation to another drive. To move the Ubuntu installation, run the following command in Windows PowerShell as administrator:
PowerShell
wsl --manage Ubuntu-22.04 --move <new_drive_path>
For example:
PowerShell
wsl --manage Ubuntu-22.04 --move D:\WSL\Ubuntu

​
DNS resolution failures in WSL

WSL may fail to resolve domain names, causing network-dependent operations, such as fetching packages or cloning repositories, to fail with DNS errors. To fix DNS resolution failures, configure DNS settings manually using the resolv.conf file:
  1. To disable automatic resolv.conf generation, in the Ubuntu terminal, run the sudo command to add the following contents in the /etc/wsl.conf file:
    /etc/wsl.conf
    [network]
generateResolvConf = false
  2. To set DNS servers in resolv.conf, in the Ubuntu terminal, run the sudo command to replace the contents of /etc/resolv.conf with your internal DNS server, followed by a public DNS server as a fallback:
    /etc/resolv.conf
    nameserver <your-internal-dns-ip>
nameserver 8.8.8.8
    WSL queries the nameservers in order. Listing the internal DNS server first ensures domains, private package registries, and virtual private network (VPN)-only resources resolve correctly.
  3. To restart WSL and apply the changes, run the following command in Windows PowerShell:
    PowerShell
    wsl --shutdown

​
Git Filename too long error in Yocto builds

When running a Qualcomm Linux Yocto build in WSL, Git may fail with a Filename too long error. The error occurs because Windows enforces a default MAX_PATH limit of 260 characters, which Yocto build paths can exceed. To fix this error, enable long path support for Git by running the following command in the Ubuntu terminal:
Ubuntu terminal
git config --global core.longpaths true

​
USB device fails to attach to WSL

If usbipd attach fails, becomes unresponsive, or the device doesn’t appear in lsusb, do the following:
  1. To confirm that usbipd has bound the device, run usbipd list in Windows PowerShell as administrator and verify that the STATE column shows Shared. If it’s Not shared, the attach fails. Bind it using the usbipd bind --busid <busid> command in Windows PowerShell as administrator.
  2. To check the networking mode, confirm that the usbipd attach output reports Detected networking mode mirrored. If it reports nat, the corporate firewall or Group Policy is blocking the connection on managed machines. To resolve this, do the following: a. Enable mirrored networking as described in Step 2 of Enable USB device access for WSL. b. Verify that the .wslconfig filename and path are correct. c. Run wsl --shutdown for the change to take effect.
  3. The BUSID can change when you unplug the device or switch modes. If the BUSID has changed, do the following: a. Re-run usbipd list to confirm the current BUSID. b. Re-run usbipd attach --wsl --busid <new-busid>. c. Confirm that WSL has the USB/IP client tools installed.
If the attach still fails after enabling mirrored networking, Group Policy may be blocking the usbipd firewall rule entirely. In this case, flash from a native Ubuntu host instead, where USB pass-through isn’t required.

​
Next step