Storage and sharing

VM packages

Each VM is a .mvz package holding its configuration, disks, saved state and snapshots, and a template is a .mvzt one. Packages from earlier builds keep their .macvisor name and work as before. Converting a VM to a template renames its package .mvzt, and back to .mvz. Nothing else renames a package: moving it to another location keeps its name.

Importing a package

Double-click a .mvz, .mvzt or .macvisor package in Finder, or run mvz import. The copy is named <name>.mvz (<name>.mvzt for a template). An imported VM gets a new identity and new MAC addresses. MacVisor also removes settings that could reach outside the VM, and lists what it changed:

• Shared folders and external disk images are removed, because they point to the other Mac's paths.
• Captured USB devices are cleared, and Start at Login, High Availability, backups and automatic snapshots are turned off.
• Port forwards listen on 127.0.0.1 only.
• A suspended session is discarded. Live snapshots keep their disks but lose their memory.

A package that points to disk files outside itself, or contains links, is refused. So is one from a newer MacVisor that uses a setting this one doesn't know: the error names the setting and its value. Update MacVisor to import it.

The same applies to a VM package that appears in a storage location without being imported: copied there in Finder, brought over from another Mac, or found on a drive you added as a location. MacVisor removes those settings in the same way, and also turns off its AI sandbox settings. A package with links in it isn't listed. A suspended session, or a live snapshot's memory, saved with those settings would bring them back, so it goes to the Trash, in a folder named <VM> saved memory <date>: the VM starts from its disk, and such a snapshot restores its disk only. On a drive with no Trash, such as a network share, the folder stays in the VM's package.

Each Mac, and each account on it, does this once for a package it didn't make. On a drive you use with two Macs, neither resets the other's VMs again, and what you set up on each stays. This holds for a Mac you set up from another with Migration Assistant too: the VMs from before the move keep their settings on both, and each Mac resets a VM made on the other only once. VMs this Mac made, imported or moved keep their settings, also when you rename or move them in Finder. If MacVisor can't read the .host-secrets folder in a VM's package, it leaves the VM out of the list until it can, rather than resetting it.

mvz import <bundle> [--location <id>] [--move]

Copies of a VM

Two packages of the same VM in your storage locations, such as a Finder duplicate, aren't both listed. MacVisor lists the one that's running, otherwise the one it last created, moved, imported or started, otherwise one it already knows as this Mac's own, and shows the other under items couldn't be loaded with both paths. To keep the copy as a VM of its own, import it: double-click it in Finder, or run mvz import <path>. It gets a new identity.

Disk format

MacVisor creates disks in ASIF, Apple's sparse disk format, unless you choose Raw for a Linux VM installed from an ISO. ASIF disks grow as the guest writes, may give freed space back, and are required for shrinking and linked clones.

Raw disks work as well and show as Raw. They can't be linked-cloned, and a copy to another drive needs their full size free. To convert one, stop the VM and click Convert to ASIF… in VM Settings → Storage. You need free space for about as much data as the disk holds, not its full size. The raw file goes to the Trash once the new disk is verified. See Disk formats and sector sizes, which also covers sector sizes.

Resizing

Disks can only change while the VM is shut down, with no suspended session.

Shrinking a macOS guest's disk checks first where its partitions end, and refuses a size below the last partition and the copy of the partition table after it, naming the least size the disk can have. On macOS the recovery container comes after the main one, so shrink or remove it in the guest first. A disk whose partition table can't be read isn't shrunk. Before it shrinks, MacVisor asks, then takes a snapshot named "Before shrinking disk" that you can revert to.

Storage locations

Add a storage location to keep VMs on another internal volume, an external APFS disk, or another mounted filesystem. Choose the location when you create a VM, or move one later.

Add Location… checks the folder first:

• A folder that iCloud or another cloud service keeps in sync is refused: iCloud Drive, Desktop & Documents when iCloud syncs them, or a provider's folder in ~/Library/CloudStorage. Syncing uploads VM disks and can remove them from the Mac to free up space, and a VM whose disk was removed can't start.
• A folder MacVisor's background service can't read is refused. Allow MacVisor Background Service under System Settings → Privacy & Security → Files & Folders, then add it again. If macOS is asking about the folder, click Allow and MacVisor adds it.
• On a network share, or a drive that isn't APFS, MacVisor asks first. There every clone, snapshot and revert copies the VM's disks in full, which takes time and as much space again, and a snapshot of a running VM keeps it paused until the copy is done. A network share also has no Trash: a disk removed there is deleted for good, and a VM there can't be moved to the Trash. Click Add Anyway to use it all the same.

A stopped VM moves directly. A running VM is suspended, moved and resumed, which needs the Mac to be unlocked.

mvz locations
mvz move <vm> <location>

Don't disconnect a drive while a VM on it is running or moving. A location on a disconnected drive shows as Offline. To pick a new default, right-click a location and choose Make Default.

When a drive gets full

A VM whose drive fills up gets write errors in the guest, which can damage its file systems. So while VMs run, MacVisor watches the free space on every drive that holds one, its disks included:

• Below 10 GB free (or 5% of a smaller drive), it warns you, once until the drive has room again.
• Below 2 GB free, it pauses every VM on that drive, so nothing more is written, and tells you. A paused VM keeps its memory and resumes where it was. MacVisor never resumes it by itself: free up space, then resume it in MacVisor or with mvz resume <vm>.

Moving, cloning or exporting a VM to another drive also leaves at least 2 GB free there.

What is stored where

To move all of this to another Mac, see Moving to a new Mac.

Backups

Time Machine doesn't back up your VMs. MacVisor leaves each VM package out of Time Machine when it's made, cloned or imported, because a VM's disks change by gigabytes between backups and a copy taken while the VM runs may not start.

• To back VMs up, turn on Back Up Automatically in VM Settings → Backup, or run mvz set <vm> --backup-to <folder>. MacVisor copies the VM, also while it runs, to a folder on another drive or a share, daily or weekly, and checks every copy. See Backups.
• To keep a copy of a stopped VM once, export it: Export… in its menu, or mvz export <vm> <folder>. The copy is <name>.mvz.
• MacVisor's backups and exports aren't left out of Time Machine.
• To have Time Machine back up a VM all the same, run tmutil removeexclusion ~/VMs/<name>.mvz (<name>.macvisor for a VM from an earlier build). MacVisor doesn't exclude it again, and moving it to another location keeps that. A clone or an import of it starts out excluded.

MacVisor also leaves out of Time Machine what it can download again: downloads in progress and macOS installers in each location's Templates folder, the guests' downloads in RuntimeCache, the guest tools image, and the AI models it downloads. It does so each time it uses them, so they stay out even if you include them again.

Storage measurements

Additional disks and media

Add or remove disks in VM Settings → Storage while the VM is shut down. Removed disks go to the Trash, so unmount them in the guest first.

Add Disk asks for the size, the Format (ASIF or Raw) and, for ASIF, the Sector Size: 512 bytes (the default), which the guest's disk tools expect, or 4 KB (native). Raw disks have 512-byte sectors. If MacVisor's background service is older than the app and makes another disk than you chose, Add Disk says so. Each disk's line in Storage shows its sector size, such as "64 GB - ASIF - 512-byte sectors". See Add a disk.

mvz disks add <vm> --size <GiB> [--format asif|raw] [--sector-size 512|4096|4k]
mvz disks remove <vm> <disk-id>    # asks first; --yes in a script
mvz set <vm> --disk <GiB>          # grow the boot disk
mvz set <vm> --iso <file|none>     # attach or eject an ISO

A cloud-image Linux VM grows its filesystem by itself at the next boot. Images on the USB bus can be attached while the VM runs.

Disk images on a running VM

An ISO or a disk image file on your Mac can be attached to a running VM as a USB drive, read-only: nothing in the guest can change it. It stays attached until the VM stops. To attach one at every start, add it in VM Settings → Storage → Disk Images instead.

• In the VM's window: VM → Attach Disk Image… chooses the file. VM → Eject lists the images attached, by file name.
• On the Overview: Attach Disk Image… on the USB Mass Storage card, which lists the images attached from anywhere.
• From Terminal: mvz usb attach <vm> --image <path>, as in Disk images as USB drives.
• An AI agent with Control of the VM: attach_disk_image and detach_disk_image. See Attach disk images.

The guest sees a new USB drive: mount it there (in Linux, lsblk shows it). Unmount it in the guest before you eject it. A suspend or a live snapshot detaches the image and attaches it again afterwards, as it does USB devices; its id changes then, and its path still finds it.

MacVisor checks the file first, whoever attaches it:

Attaching is refused while Allow Attaching USB Images While Running is off in VM Settings → Storage; turned on, it works at once, without a restart. If macOS keeps the VM out of the folder the image is in (Desktop, Documents or Downloads), MacVisor says so: move the file to another folder.

USB devices

A VM can use a USB device plugged into the Mac, such as a security key, a serial adapter or a Zigbee radio, and remember it so it's attached whenever the VM runs. See USB devices.

Shared folders

Share Mac folders with a guest in VM Settings → Shared Folders, read-only or read-write. From the CLI:

mvz shares <vm> add ~/src/app
mvz shares <vm> add ~/Documents --read-only
mvz shares <vm> remove ~/src/app

Changes apply when the VM next starts from shut down.

Cloud-image Linux VMs share nothing unless you ask. --home shares your home folder read-only at the same path.

Oracle Linux mounts them a little later

Oracle Linux's kernel doesn't include the driver shared folders need. After the first boot, the agent downloads it in the background, which can take several minutes, and then mounts the shares. From then on they mount at every boot.