Introduction
Apple’s Virtualization framework runs a macOS virtual machine on Apple silicon from a handful of
files that the program keeps together: the disk, the auxiliary storage macOS needs, and two small data blocks that name the virtual hardware. There is no
standard extension: Apple’s sample code calls the folder VM.bundle, and other programs name it as they like (.macvm is what a
real bundle on this site’s owner’s Mac, made by Parallels Desktop, is called).
This page says, for each file, what Apple documents and what was only seen in that real bundle. Documented comes from Apple’s page “Running macOS in a virtual machine on Apple silicon” (the sample code’s article, read as raw JSON on 2026-11-14); observed comes from the real bundle, read only; nothing was started.
The layout Apple defines
The sample’s InstallationTool creates a VM.bundle package in the home folder containing:
| File | What Apple says |
|---|---|
Disk.img | The main disk image of the installed OS. (The sample makes a 128 GB image; the pages read do not give its format.) |
AuxiliaryStorage | The auxiliary storage for macOS (a VZMacAuxiliaryStorage; it “contains the boot configuration and NVRAM”, as the sample’s comment on copying it says). |
MachineIdentifier | The data representation of the VZMacMachineIdentifier object: it identifies this machine and tells it from any other. |
HardwareModel | The data representation of the VZMacHardwareModel object: the hardware model the restore image supports. |
RestoreImage.ipsw | The restore image downloaded from the network; present only if the tool ran without arguments. |
SaveFile.vzvmsave | Not made by the installer: the state the sample app saves with saveMachineStateTo(url:) when you close it, restores with restoreMachineStateFrom(url:) at the next launch and then deletes, “because the VM disk no longer matches the state in the file”. |
The sample reads the hardware model and the identifier back with VZMacHardwareModel(dataRepresentation:) and VZMacMachineIdentifier(dataRepresentation:) from the files’ bytes,
so the bytes are exactly the object’s data representation; Apple does not describe what is inside them. In macOS 27’s sharedBaseImageSampleApp two VMs share one
read-only base Disk.img, each stacking an overlay on it with DiskImageKit (.asifLayer(url:type: .overlay), an ASIF layer) and keeping its own copy of
AuxiliaryStorage and its own MachineIdentifier; the sample says an overlay becomes incompatible when the base image is modified.
What a real bundle holds (observed)
A macOS guest made by Parallels Desktop (macOS.macvm, a machine of 4 CPUs and 8 GB running macOS 26.4.1). It is a Parallels machine bundle
(it has config.pvs and its backup, VmInfo.pvi, parallels.log, statistic.log, and a suspended state) in which the framework’s data sit under other names:
| File here | Apple’s name for it | Seen |
|---|---|---|
machw.bin | HardwareModel (by role) | 132 bytes: a binary property list (bplist00) with DataRepresentationVersion 2, PlatformVersion 2 and MinimumSupportedOS [13, 0, 0]. So in this bundle the hardware model’s data representation is a property list. |
macid.bin | MachineIdentifier (by role) | 68 bytes: a binary property list with one key, ECID, an integer (here 13147539656117030512, 0xB67571A899378E70). |
aux.bin | AuxiliaryStorage (inferred) | 33,579,164 bytes; it starts A5 D5 B3 FE 97 AD 1D 27 02 00 00 00 00 00 00 00 01 00 00 00 …. Which Apple file it is is inferred from the size, the neighbours and the role; no source states it. Apple does not describe its inside. |
harddisk.hdd/ | Disk.img (by role) | A Parallels disk bundle of one Plain image: harddisk.hdd.0.{…}.hds, 137,438,953,472 bytes (exactly 128 GiB). It is a raw disk, not ASIF: its first sector is all zeros and bytes 512 to 519 read EFI PART, a GPT header at the second sector. The first sector holds no protective MBR. |
config.sav | SaveFile.vzvmsave (by role) | 3,623,882,752 bytes; the first 8 bytes are 65 76 61 53 4D 56 5A 56, which spell VZVMSave when read as a little-endian 64-bit number, then 01 00 00 00 00 00 00 00. The rest is not documented. |
suspended.png | – | A 3.5 MB PNG, the screen when the machine was suspended (by its name). |
In the explorer
Drop the bundle folder. The folder view recognises Apple’s file names (Disk.img, AuxiliaryStorage, HardwareModel, MachineIdentifier,
SaveFile.vzvmsave, RestoreImage.ipsw) and the names Parallels uses (machw.bin, macid.bin, aux.bin, config.sav).
It decodes the two property lists into their keys and values, shows the first bytes of the other files (with the VZVMSave header and a GPT header recognised) and says
which statements are documented and which observed. A bundle that has a config.pvs is also shown as a Parallels machine, and its disk folder as a Parallels disk
bundle. The disk opens in the explorer as a Parallels image; a Plain image is the raw disk.
Not described
Known, not yet covered
- Reference: ASIF layers (DiskImageKit) and stacked images are named in the sample; the pages read do not give the ASIF format, so a real
Disk.imgmade by Apple’s sample (which may be an ASIF file) cannot be opened by its structure yet. - Viewer: the folder view shows
Disk.img,AuxiliaryStorageand the saved state as first bytes; it does not open them as levels.
Unknown
- Reference: the inside of
AuxiliaryStorage(aux.bin), of the saved state (SaveFile.vzvmsave,config.sav) and the meaning of the property lists’ values (PlatformVersion,MinimumSupportedOS,ECID) are not documented in any source read.
Links
Software
- Parallels Desktop – makes macOS guests whose data use these files (macOS)
Developers
- Virtualization framework – Apple’s framework for running macOS and Linux virtual machines (Swift, Objective-C)
Reference
- Running macOS in a virtual machine on Apple silicon – Apple’s sample code and the VM.bundle layout