Working with WSL and VMware Shared Folders

Working with WSL and VMware Shared Folders

A practical reference for setting up and troubleshooting a WSL-based development environment, attaching USB devices, and sharing files with VMware virtual machines.

Accessing WSL Files from Windows

WSL's Linux filesystem isn't a normal Windows path, but it's reachable from File Explorer:

\\wsl$\

or on newer Windows builds:

\\wsl.localhost\

This lists your installed distros (e.g. \\wsl$\Ubuntu-24.04) and lets you browse into the Linux filesystem. Occasional access this way is fine, but for regular editing, prefer a WSL-aware editor (e.g. VS Code's "Remote - WSL" extension) rather than editing Linux files through Windows tools.

The reverse also works: Windows drives are automatically mounted inside WSL under /mnt/, e.g. /mnt/c/Users/... or /mnt/e/ for a drive letter E:.

Avoid cloning git repositories onto /mnt/c/.... The NTFS mount doesn't fully support Linux permission bits, which breaks chmod and git's core.filemode handling:

error: chmod on /mnt/c/Users/.../.git/config.lock failed: Operation not permitted
fatal: could not set 'core.filemode' to 'false'

Clone into your Linux home directory instead (~/project) — it's also significantly faster than crossing the Windows/Linux filesystem boundary.

Running Multiple WSL Terminals

WSL fully supports concurrent sessions into the same distro. Just open another terminal and run:

wsl -d Ubuntu-24.04

Both sessions share the same filesystem, processes, and running services (e.g. Docker containers) — they're independent shells over one Linux environment.

Restarting WSL

Some changes (like group membership updates) require a full WSL restart to take effect. From PowerShell:

wsl --shutdown

This stops all running WSL instances. No separate "start" command is needed — WSL boots automatically the next time you run wsl or open a WSL terminal.

Installing or Switching Ubuntu Versions

To see available distros and install a new one:

wsl --list --online
wsl --install -d Ubuntu-24.04

To remove an existing distro (this permanently deletes its entire filesystem — back up anything important first):

wsl --list -v
wsl --unregister <DistroName>

Newer Ubuntu releases ship newer default Python versions without needing extra PPAs — e.g. 22.04 ships Python 3.10, 24.04 ships Python 3.12. This matters for tools using modern syntax (like match statements, which require 3.10+).

Docker Desktop + WSL Integration

If a project uses a Docker-based build runner, you need Docker Desktop's WSL integration enabled for your specific distro:

1. Open Docker Desktop → Settings → Resources → WSL Integration.
2. Enable integration for your distro (e.g. Ubuntu-24.04).
3. Apply & Restart.

Verify from WSL:

docker --version
docker run hello-world

If you hit permission denied while trying to connect to the Docker daemon socket, your user isn't in the docker group yet:

sudo usermod -aG docker $USER

Then restart WSL (wsl --shutdown from PowerShell, then reopen) for the group change to apply. Confirm with:

id -nG

docker should now appear in the group list.

USB Device Passthrough (usbipd-win)

WSL2 doesn't see USB devices by default — Windows owns them. To use a USB device (card reader, dev board, etc.) inside WSL, pass it through with usbipd-win.

Install (Windows, PowerShell)

winget install usbipd

Close and reopen PowerShell afterward so PATH refreshes.

List devices

usbipd list

Shows connected USB devices, their BUSID, and sharing state (Not shared / Shared / Attached).

Bind and attach

Both commands take the BUSID from usbipd list (e.g. 4-2):

usbipd bind --busid 4-2
usbipd attach --wsl --busid 4-2

• bind requires an elevated (Administrator) PowerShell window and only needs to be done once per device — it persists across reboots.
• attach connects the device to WSL for the current session; you'll need to re-run it after each reboot or replug (or use --auto-attach to reattach automatically).

Confirm inside WSL:

lsblk        # for storage devices — shows the new block device, e.g. /dev/sda
lsusb        # general USB device listing (install via: sudo apt install usbutils)

Detach and unbind

usbipd detach --busid 4-2     # disconnect from WSL, give back to Windows
usbipd unbind --busid 4-2     # fully stop sharing (undoes bind)

detach alone is usually enough for routine use — you can reattach anytime without rebinding.

Troubleshooting

• usbipd not found for kernel ... warning: usually benign — WSL2 dynamically constructs a kernel-specific package name that rarely exists in Ubuntu's repos. First try wsl --update followed by wsl --shutdown, since modern WSL kernels have USBIP support built in. If a real block persists on attach, install fallback tools inside WSL:

  sudo apt install -y linux-tools-generic hwdata
  sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20
  

• Access denied; this operation requires administrator privileges: bind (and sometimes attach) needs an elevated PowerShell. Open PowerShell/Terminal via "Run as administrator" — the title bar should read "Administrator: ..." and the default working directory will be C:\WINDOWS\system32.
• Always run usbipd commands from a native Windows PowerShell window, not through WSL interop.

VMware Shared Folders

VMware Workstation/Fusion offers a separate, simpler mechanism for sharing host files with a VM, without needing full USB passthrough.

Enabling shared folders

1. With the VM powered off (or via VM → Settings while running, for some versions): go to VM → Settings → Options → Shared Folders.
2. Choose Always enabled or Enabled until next power off.
3. Click Add, pick the host folder, and give it a share name.
4. Ensure VMware Tools (or open-vm-tools on Linux guests) is installed in the guest — shared folders depend on it.

Mounting inside a Linux guest

Modern VMware Tools/open-vm-tools usually auto-mount shares under:

/mnt/hgfs/<share-name>

If it's not mounted automatically:

sudo mkdir -p /mnt/hgfs
sudo vmhgfs-fuse .host:/ /mnt/hgfs -o allow_other -o uid=$(id -u) -o gid=$(id -g)

To make this persistent across reboots, add an entry to /etc/fstab:

.host:/    /mnt/hgfs    fuse.vmhgfs-fuse    allow_other,defaults    0    0

Windows guests

Shared folders appear automatically under *This PC → \vmware-host\Shared Folders* once VMware Tools is installed, no manual mounting needed.

Notes

• Shared folders are host↔guest only — they don't require network configuration and work regardless of the VM's network mode (NAT/Bridged/Host-only).
• For raw block-device access from a VM (e.g. flashing a physical SD card), it's usually more reliable to pass the USB device through directly via VM → Removable Devices rather than using shared folders.

Quick Reference

Task	Command
Access WSL files from Windows	\\wsl$\ in File Explorer
Access Windows files from WSL	/mnt/c/...
Start/switch WSL distro	wsl -d <DistroName>
Restart WSL (apply group/config changes)	wsl --shutdown
List/remove distros	wsl --list -v / wsl --unregister <name>
Fix Docker permission denied	sudo usermod -aG docker $USER then wsl --shutdown
List USB devices (Windows)	usbipd list
Share + attach USB device to WSL	usbipd bind --busid <ID> then usbipd attach --wsl --busid <ID>
Detach/unshare USB device	usbipd detach --busid <ID> / usbipd unbind --busid <ID>
Mount VMware shared folder (Linux guest)	sudo vmhgfs-fuse .host:/ /mnt/hgfs -o allow_other