Attach a Separate VHDX Data Disk to WSL 2 Safely

A separate VHDX can give a WSL 2 workload an independently managed Linux data filesystem instead of mixing that data with the distribution’s root filesystem. The important distinction is that the VHDX is a virtual disk container, while Linux sees a block device and filesystem after WSL attaches it. Attaching is not the same as formatting, partitioning, mounting, making the mount persistent, or backing up the data. Each step has a different failure mode, and guessing the device name can damage the wrong filesystem.

This workflow is for a user-managed data disk, not for opening a live distribution’s own ext4.vhdx. Do not attach or edit the VHDX backing a running distro as if it were an independent disk. Microsoft specifically warns to shut WSL down before interacting with a distro’s VHDX, and that recovery workflow belongs to a separate offline-maintenance procedure.

Check the supported attach path first

Microsoft documents direct wsl --mount --vhd <pathToVHD> support for Windows 11 or the Microsoft Store version of WSL. Attaching a disk requires administrator privileges. A disk already in use by Windows cannot be attached, and WSL attaches the entire disk even when a selected partition is requested. Do not use the Windows installation disk. Check the local host and command surface before planning a migration:

wsl.exe --version
wsl.exe --help

If direct VHD attachment is not available in the installed servicing path, Microsoft documents an alternative that first attaches the VHD in Windows with Hyper-V’s Mount-VHD, obtains its PhysicalDrive path, and then supplies that disk path to wsl --mount. That alternative has its own Windows feature/module and privilege requirements. Do not assume the command syntax is identical on every inbox or Store WSL version.

Keep the VHDX on a local volume with enough free space and a backup policy. A VHDX is a storage container, not a backup. A host-side copy made while it is mounted and receiving writes may be inconsistent. Stop the workload, unmount cleanly, detach the disk, and only then take a cold file-level copy unless your backup system explicitly supports a consistent live snapshot.

Establish an inventory before attaching

Choose the Linux distribution that will own the mount and the intended mountpoint. Record the VHDX path, expected virtual capacity, filesystem type, partition layout, and an independent backup. If the disk contains valuable data, capture a baseline before the maintenance window. Avoid a Format-Volume, Initialize-Disk, or Linux mkfs command unless the disk is intentionally blank and you have independently verified its identity.

For a VHDX that already contains a Linux filesystem, attach it without asking WSL to guess a mount:

# Run in an elevated PowerShell session. Replace the path with the data VHDX.
wsl.exe --mount --vhd "D:\WSLData\analytics.vhdx" --bare
wsl.exe --distribution Ubuntu --exec lsblk --fs

--bare exposes the block device to WSL without mounting it. lsblk --fs and blkid provide Linux-side evidence about device size, partitioning, and detected filesystem. Device names such as /dev/sdb are assigned at runtime; they are not persistent identities. Do not copy a device name from an example or prior boot and assume it still identifies the same disk.

Identify the filesystem before mounting

Inside the intended distro, compare the new device against the pre-attach inventory. Look for the expected capacity and filesystem label/UUID, and verify the partition tree:

lsblk -o NAME,SIZE,TYPE,FSTYPE,LABEL,UUID,MOUNTPOINTS
sudo blkid

Only after matching the expected disk should an operator choose the filesystem device. The following is illustrative: replace /dev/sdX1 with the verified partition shown on your host. If the filesystem is directly on the whole disk, use the verified whole-disk device instead. Do not run mkfs on an existing filesystem; it creates a new filesystem and destroys the prior directory structure.

sudo install -d -m 0750 /srv/analytics
sudo mount /dev/sdX1 /srv/analytics
findmnt /srv/analytics
df -hT /srv/analytics

Check ownership and permissions against the Linux user that runs the workload. If the filesystem is ext4, the device is presented as Linux block storage; Windows does not thereby gain a normal drive-letter mount. WSL’s documentation notes that a disk mounted through WSL is available from Windows through the WSL network namespace path, but applications should be tested with the intended access path and permissions rather than assumed to behave like a Windows volume.

Persistence is an explicit design choice

An interactive mount disappears when it is unmounted or the WSL environment stops. If the application needs a persistent mount, decide how WSL should attach the host-side VHDX and how Linux should mount the filesystem at distribution startup. Do not put a guessed /dev/sdX path into /etc/fstab; Linux device enumeration can change. Use a stable filesystem identifier such as a verified UUID only after checking the filesystem’s own documentation and your distro’s mount behavior.

WSL’s wsl.conf automount and boot settings are per-distribution configuration, while .wslconfig is global WSL VM configuration. They solve different layers and do not by themselves guarantee that a separately attached VHDX exists before Linux boot tries to mount it. Build an explicit startup/attachment dependency and test cold start, wsl --shutdown, Windows reboot, and a detached-disk case. If startup fails because a required disk is absent, recovery should remain possible without editing the root filesystem offline.

For a workload that can tolerate manual attachment, a deliberate operator sequence is often safer: attach the image, inspect it, mount it, verify the application, stop writes, unmount, then detach. For unattended operation, document who owns the host-level attach, how failure is surfaced, and whether the application should fail closed or start without the data mount. Never let an application silently create an empty directory tree on the root filesystem when its intended data disk is missing.

Flush writes and detach in the right order

Before detaching, stop writers and confirm no process has its current directory or open file on the mount. Flush filesystem buffers, unmount the Linux filesystem, and verify that it no longer appears in findmnt:

sync
sudo umount /srv/analytics
findmnt /srv/analytics || true

Then detach from an elevated PowerShell session. wsl --unmount with a specific disk path detaches that disk; omitting the path unmounts and detaches all attached disks. Use the broad form only when you have confirmed no unrelated WSL-attached disks need to remain available:

wsl.exe --unmount

If a specific-disk detach fails, do not immediately force-close Windows or copy the VHDX. Locate open Linux processes, resolve the mount busy condition, and retry. Microsoft documents wsl --shutdown as a way to force WSL to exit if unmounting fails; it will also stop all running distributions and detach disks, so treat it as a disruptive recovery action, not a routine detach command.

Failure cases and recovery evidence

If WSL says a disk is in use, confirm Windows has not mounted it or left a handle open, and confirm no other process is consuming the VHD. If no Linux block device appears, verify the elevation level, WSL version, path spelling, virtual disk state, and supported attach syntax. If blkid reports no recognized filesystem, stop before formatting: the VHD may be blank, partitioned unexpectedly, encrypted, damaged, or using a filesystem unsupported by the current kernel. Preserve a copy and investigate the partition table and filesystem offline.

If the mount succeeds but files seem absent, first inspect lsblk, blkid, findmnt, the selected partition, and the mountpoint. Mounting a different empty partition can make a valid disk appear empty. If the application writes to the mountpoint while the disk is absent, it may populate the underlying root filesystem directory; repair that condition with the application stopped and reconcile the two data trees before restarting.

Acceptance should prove both the storage path and lifecycle: the expected UUID is mounted at the intended path, read/write permissions match the service account, a controlled test file persists after a clean unmount and reattach, the workload can open its data, and the VHDX can be copied only after detach. Record the VHDX path, owner, filesystem UUID, mount configuration, backup method, and exact detach command. That turns a convenient extra disk into an operable storage dependency rather than an undocumented point of failure.

Related:

Sources: