The constraint behind this guide

VZDiskImageStorageDeviceAttachment, the API every Virtualization.framework app uses to attach a disk, reads raw disk images only: no QCOW2, VMDK, VHD or VHDX. When you create a workspace with Boot from an existing virtual disk, Velo Workspaces reads the file's header rather than trusting its extension, and handles each format accordingly:

  • Raw (.img, .raw): attached as it is.
  • QCOW2 (.qcow2): since 1.2, converted to raw on the way in, by the same code that turns cloud images into workspaces. No extra tools needed.
  • VMDK, VHD, VHDX and Parallels disks: the app tells you what it found and the command that converts it:
"This is a [format] disk image, which Apple's Virtualization framework cannot read — it attaches raw images only. Convert it first with: qemu-img convert -O raw source destination.img"

This guide expands that per hypervisor, with where each one keeps its disk.

Scope: Linux guests

This covers Linux VMs. Velo Workspaces doesn't run Windows guests (why, and what to use instead). macOS guests aren't covered either, because UTM, VMware Fusion and Parallels each store a macOS guest's disk and platform data differently.

Also check the architecture. On an Apple silicon Mac, Velo Workspaces runs arm64 guests; an x86-64 Linux VM from an Intel Mac, or one UTM was emulating, won't boot here however you convert it. On an Intel Mac it's the other way round.

From UTM: no conversion needed

UTM stores a Linux VM's disk as QCOW2. In Finder, right-click the .utm file, choose Show Package Contents, and look in the Data/ folder for a .qcow2 file. (If UTM came from the Mac App Store, the bundle lives in UTM's sandboxed container; Show Package Contents finds it either way.) Shut the VM down in UTM first, then in Velo Workspaces create a workspace, choose Boot from an existing virtual disk, and drop in that .qcow2. The app converts it to a raw workspace disk and leaves the original untouched.

The same works for QCOW2 disks from Lima, Multipass or plain QEMU.

Before the other two: install qemu-img

VMware and Parallels disks convert with QEMU's qemu-img, the reference tool for all these formats. Install it with Homebrew:

brew install qemu

qemu-img comes with the qemu formula; check it with qemu-img --version.

A raw image's apparent size is the guest's full configured disk size, even if the source only used a fraction of it. qemu-img writes it sparsely, so on APFS it only takes about as much space as the data, but tools that copy the file naively can inflate it. Keep some headroom, and move it with Finder or cp rather than tools that don't preserve sparseness.

From VMware Fusion

Right-click the .vmwarevm bundle, Show Package Contents, and find the .vmdk. Slow down here: VMware sometimes stores a disk as one .vmdk, and sometimes as a small text descriptor file (a few KB) plus data files named like diskname-s001.vmdk, diskname-s002.vmdk and so on. Always give qemu-img the descriptor, the small file, often just diskname.vmdk, never a numbered extent. The descriptor references every extent, and qemu-img follows them to produce one complete file; pointing it at an extent gives you a truncated, useless image.

qemu-img convert -f vmdk -O raw "/path/to/VMName.vmwarevm/Virtual Disk.vmdk" destination.img

From Parallels Desktop

Parallels nests one level deeper: a .pvm bundle contains a .hdd package, which contains the data file, named like disk-0.hdd.0.{uuid}.hds. Show Package Contents on the .pvm, then on the .hdd inside it, to find the .hds file.

qemu-img convert -f parallels "/path/to/VMName.pvm/disk.hdd/disk-0.hdd.0.{uuid}.hds" -O raw destination.img

QEMU's Parallels reader is less well tested than its QCOW2 or VMDK support; it's documented mostly for forensics and recovery rather than routine migration. If the conversion fails or the result won't boot, first convert the disk to Parallels' "plain" (uncompressed, fixed-size) format with Parallels' own prl_disk_tool convert --hdd /path/to/disk.hdd --plain, then run qemu-img on the result.

Importing the converted image

With a .img file, create a workspace, choose Boot from an existing virtual disk, and select it. What comes across is the disk's contents: installed packages, files and configuration. What doesn't: hypervisor settings like shared folders, snapshots or custom devices, which live in each app's VM definition rather than on the disk. Set those up again in Velo Workspaces.

What usually doesn't need fixing: Linux mounts filesystems by UUID rather than device path, so a guest built on QEMU's virtio devices generally boots on Apple's virtio devices without editing /etc/fstab. If it doesn't come up cleanly, check the console before assuming the conversion failed; it's more often a display or boot loader question than a filesystem one.

Once it's running, type your account's username in the workspace's Access tab, sign in once with the password and click Install Key, and the built-in terminal (Pro) signs in without a password from then on.

Or skip the migration: if you mostly need a clean Ubuntu, Debian, Fedora or Rocky Linux, a new workspace from an official cloud image is ready in about a minute, and you can copy your project in through a shared folder.

Related reading: what a VM on Apple Silicon is, the comparison with Parallels and UTM, and the device inventory of the VM you're moving into. Or download Velo Workspaces and try it yourself.