> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Set up WSL on Windows and install Ubuntu
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
The following table lists the minimum hardware resources the WSL environment needs for Qualcomm Linux builds:
| Requirement | Specification |
| ---------------------- | -------------------- |
| Processor architecture | X64 |
| CPU cores | 8 or more |
| RAM | 16 GB or more |
| Storage | 400 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](https://documentation.ubuntu.com/wsl/latest/howto/install-ubuntu-wsl2/).
Older versions of Windows don't support installing WSL through the Microsoft Store and require manual installation. For instructions, see [Manual installation steps for older versions of WSL](https://learn.microsoft.com/en-us/windows/wsl/install-manual?source=recommendations).
## 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:
```ini title="/etc/wsl.conf" theme={null}
[automount]
options = "metadata"
[boot]
systemd=true
command = systemctl start docker
```
2. In Windows PowerShell, run the following command to restart WSL:
```powershell title="PowerShell" theme={null}
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](https://github.com/dorssel/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 title="PowerShell" theme={null}
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 title="PowerShell" theme={null}
@"
[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 title="PowerShell" theme={null}
wsl --shutdown
```
4. In the Ubuntu terminal, run the following command to install the USB/IP client tools:
```bash title="Ubuntu terminal" theme={null}
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 title="PowerShell" theme={null}
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.
```text title="Sample output" theme={null}
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 title="PowerShell" theme={null}
usbipd bind --busid 1-4
```
Binding persists across reboots, so you only need to do it once per device.
8. Replace `1-4` with your actual `BUSID`. The device's `STATE` changes to `Shared`.
9. In Windows PowerShell, run the following command to attach the device to WSL:
```powershell title="PowerShell" theme={null}
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 `. 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.
10. In the Ubuntu terminal, run the following command to confirm that Ubuntu detects the device:
```bash title="Ubuntu terminal" theme={null}
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](https://dragonwingdocs.qualcomm.com/Key-Documents/Flash-Guide/flash-with-qdl).
11. To detach the device after flashing, run the following command in Windows PowerShell:
```powershell title="PowerShell" theme={null}
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](https://learn.microsoft.com/en-us/windows/wsl/wsl-config).
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 title="PowerShell" theme={null}
wsl --manage Ubuntu-22.04 --move
```
For example:
```powershell title="PowerShell" theme={null}
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:
```ini title="/etc/wsl.conf" theme={null}
[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:
```bash title="/etc/resolv.conf" theme={null}
nameserver
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 title="PowerShell" theme={null}
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:
```bash title="Ubuntu terminal" theme={null}
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 ` 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](#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 `.
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**
* [Sync, build, and flash Qualcomm Linux](https://dragonwingdocs.qualcomm.com/Key-Documents/Flash-Guide/flash-with-qdl)