WSL2 How-to: Prepare and Attach Virtual Drives (VHD)


  • Once installation completes, note down the WSL version number:
  • Perform quick verification from a PowerShell prompt to ensure the correct version is effective:

Create and Attach VHD to WSL2 Distro

Create Virtual Drive

The following command uses the PowerShell New-VHD cmdlet to create a dynamic (expandable) virtual disk with 10GB capacity at path C:\Users\<username>\wsl2-shared.vhdx:

PS C:\> New-VHD -Path $env:USERPROFILE\wsl2-shared.vhdx -Dynamic -SizeBytes 10GB

Attach Raw Disk to WSL 2 Distro

To attach the new disk to an existing WSL2 distro named Ubuntu-20.04, run the following, specifying option --bare:

PS C:\> wsl -d Ubuntu-20.04 --mount --vhd $env:USERPROFILE\wsl2-shared.vhdx --bare
The operation completed successfully.

Verify New Disk Details

To verify the disk has been attached to distribution named Ubuntu-20.04:

  • Login
PS C:\> wsl -d Ubuntu-20.04
  • Run lsblk and examine the output
$ lsblk

sdd 8:48 0 10G 0 disk
  • The above displays the 10GB drive with name sdd
  • parted can also be used to verify
$ sudo parted /dev/sdd print

Initialise Disk

To intialise the disk, the following will need to be performed:

  1. Create partition table
  2. Create partition
  3. Format with ext4 and label partition

Create Partition table

  • An msdos partition table can be created using parted:
~ $ sudo parted /dev/sdd mklabel msdos

Create Partition

  • Create an ext4 partition, using all unallocated disk space:
~ $ sudo parted -a optimal /dev/sdd mkpart primary ext4 0% 100%
  • Verify the partition details using lsblk:
~ $ lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT /dev/sdd
sdd 10G
└─sdd1 10G

Format and Label Partition

  • Format partition with ext4 filesystem using mkfs.
~ $ sudo mkfs.ext4 /dev/sdd1
  • Note down the partition UUID value as listed in your output. It will be required for testing and establishing appropriate entry in /etc/fstab
  • In this example, the UUID is e9999b9b-5a8e-41e1-9881-a2f766838798
  • Assign a partition label (for this example, label name is vhd-part1):
~ $ sudo e2label /dev/sdd1 vhd-part1
  • Confirm the filesystem and partition details

Test Mount of ext4 Partition

Before setting up an entry in /etc/fstab, a quick test is carried out to ensure there are no issues when attempting to mount the partition.

Finding Partition UUID

  • Confirm the disk/partition name by running blkid
~ $ sudo blkid
/dev/sdd1: LABEL="vhd-part1" UUID="e9999b9b-5a8e-41e1-9881-a2f766838798" BLOCK_SIZE="4096" TYPE="ext4" ....
  • Ensure the UUID for the partition in the output above matches the one we noted previously, i.e.
  • The UUID will be used to perform the mount

Manual Mount using UUID

  • Create a mount point for the test:
~ $ mkdir -p /home/<username>/vhd-part1
  • Mount using UUID:
~ $ sudo mount UUID=e9999b9b-5a8e-41e1-9881-a2f766838798 /home/<username>/vhd-part1
  • Check by listing mounts:
~ $ mount -l | grep vhd-part1
/dev/sdd1 on /home/<username>/vhd-part1 type ext4 (rw,relatime) [vhd-part1]
  • Create test file at the new mount point:
~ $ sudo touch /home/<username>/vhd-part1/test
  • Check the file has been created as expected:
~ $ ls /home/<username>/vhd-part1/test

  • Clean up:
~ $ sudo rm /home/<username>/vhd-part1/test
  • Unmount:
~ $ sudo umount /home/<username>/vhd-part1

Add Entry for Mount in /etc/fstab

By default, a WSL distribution automatically processes mounts contained in /etc/fstab. This behaviour can be modified by altering the mountFsTab parameter, which resides in the distribution's /etc/wsl.conf file. Refer to official documentation for further details.

  • Append the following single-line entry to the WSL distribution /etc/fstab file
UUID=e9999b9b-5a8e-41e1-9881-a2f766838798       /home/<username>/vhd-part1    ext4    defaults     0       2
  • In an environment where multiple WSL distros are installed (e.g. Kali and Ubuntu), the above entry will need to be added to each distribution's /etc/fstab file where the mount is required

Attaching the VHD at Session Start-up

Create/Modify Terminal Session

When logging into our distro via a Terminal session, we need to ensure the disk is attached before the /etc/fstab entry to be processed.

PS C:\> wsl -d Ubuntu-20.04 --mount --vhd C:\Users\<username>\wsl2-shared.vhdx --bare | out-null
PS C:\> wsl -d Ubuntu-20.04
pwsh.exe -Command "wsl.exe -d Ubuntu-20.04 --mount --vhd C:\Users\<username>\wsl2-shared.vhdx --bare | out-null; wsl.exe -d Ubuntu-20.04"

Test Terminal Session

  • Launch session
  • Check mount has been processed by running
$ mount -l | grep vhd-part1

Detaching a VHD

Once the virtual disk is attached using wsl --mount --vhd <path>, it remains attached until the host is rebooted, or WSL is shutdown.

PS C:\> wsl --unmount \\?\C:\Users\<username>\wsl2-shared.vhdx



Learner. Interests include Cloud and Devops technologies.

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Tony Tannous

Tony Tannous


Learner. Interests include Cloud and Devops technologies.