MacVisor GA

Backups

Keep copies of your VMs with mvz export, back up running VMs with another backup tool through a disk-only snapshot, and restore a VM from its copy.

Snapshots live inside a VM's package, so they are not a backup. A backup is a copy of the VM somewhere else, as a package that mvz import takes on any Mac.

What MacVisor does

  • Time Machine leaves VMs out. MacVisor excludes each VM package from Time Machine. See Storage and sharing for why, and how to include one anyway.
  • Export a stopped VM: Export… in its menu, or mvz export <vm> <folder>. The copy is <name>.mvz, with its snapshots.
  • Export a snapshot, also of a running VM: Export… in the VM's Snapshots tab, or mvz snapshots export. See Snapshots and recovery.

Back up a running VM with another backup tool

Backup tools such as Archiware P5, Carbon Copy Cloner or Arq can back up a running VM through their pre- and post-backup scripts. The pre-script takes a disk-only snapshot and exports it. The tool then backs up the export.

mvz snapshots take <vm> --disk-only --json:

  • asks the guest agent to flush the guest's file systems first (Linux and macOS; Windows flushes on its own);
  • pauses the VM only while APFS clones its disk files, then resumes it. On 27 Oct 2026 this took about 0.05 to 0.27 s, and up to a couple of seconds on a very busy Mac. Network connections don't drop;
  • doesn't save the VM's memory.

The result is crash-consistent, like a power cut: there is no VSS or application quiescing. On a drive that isn't APFS, the disks are copied in full while the VM is paused, so keep VMs you back up this way on APFS.

mvz snapshots export <vm> <snapshot-id> <folder> --name <name> --json then writes <folder>/<name>.mvz, a VM of its own that imports on any Mac. A layered disk, such as a linked clone's or a cloud-image VM's, is written out as one disk.

  • The take command prints the snapshot's id at result.snapshotID. The export prints the bundle's path at result.bundlePath.

  • A name that's taken gets -2, -3 and so on. Remove the previous export first to keep the path the same.

  • Delete the snapshot once the export is written: mvz snapshots delete <vm> <id> --yes. The export doesn't need it.

  • Export to a folder outside your storage locations; MacVisor refuses one inside them. Time Machine isn't told to skip the export.

  • Run the scripts as the user whose VMs they are, while that user is logged in: mvz talks to that user's MacVisor service.

  • Backup tools often run their scripts as root. Then run each mvz command as that user, in their login session:

    launchctl asuser "$(id -u alice)" sudo -u alice /usr/local/bin/mvz snapshots take dev --disk-only --json

    Replace alice with the user whose VMs they are.

Example scripts

These read the JSON with jq, which comes with macOS. Set vm, dest and name to yours.

Pre-backup script:

#!/bin/zsh
set -euo pipefail

vm="web"
dest="/Users/Shared/VM Backups"   # outside your storage locations
name="web"                        # the export is "$dest/web.mvz"

rm -rf -- "$dest/$name.mvz"       # last run's export, so the name is free

id=$(mvz snapshots take "$vm" --disk-only --name "Backup" --json | jq -r '.result.snapshotID')
trap 'mvz snapshots delete "$vm" "$id" --yes >/dev/null' EXIT   # also if the export fails

bundle=$(mvz snapshots export "$vm" "$id" "$dest" --name "$name" --json | jq -r '.result.bundlePath')
echo "Exported $bundle"

Post-backup script, to free the space once the tool has the copy:

#!/bin/zsh
set -euo pipefail
rm -rf -- "/Users/Shared/VM Backups/web.mvz"

Point the backup tool at /Users/Shared/VM Backups/web.mvz. If the pre-script fails, it exits non-zero, so the tool can stop or warn.

Restore a VM

Double-click the .mvz in Finder, or run mvz import <bundle>. The VM comes back with a new identity: a new id and new MAC addresses, so it gets a new IP address unless you reserve one for it. Settings that reach outside the VM, such as shared folders and start at login, are reset. See Importing a package.

A VM restored from a snapshot export starts from its disk, as after a power cut.

What a backup contains

An export holds the VM's disks, settings and firmware. mvz export also takes its snapshots. A snapshot export takes only that snapshot, without memory or logs. Neither holds shared folders or disk images attached from outside the VM: back those up with the Mac's own files.

The account password MacVisor keeps for a VM follows mvz export's rules:

  • A macOS VM that has booted: left out.
  • A Windows VM or an Ubuntu Desktop VM: kept, so Copy Password works after a restore.
  • A VM whose password was deleted, with Delete Password… or by itself after setup: there is none to keep.

The export isn't encrypted. Keep it on an encrypted drive, or in a backup tool that encrypts. See Security model.