MacVisor

USB devices

Pass a USB device from the Mac through to a VM, keep it attached at every start, what macOS asks first, and which devices work.

A VM can use a USB device plugged into the Mac, such as a security key, a serial adapter, or a Zigbee or Z-Wave radio for Home Assistant. MacVisor passes the device through: the guest sees it as if it were plugged into the VM, and uses its own driver for it. While the VM has the device, the Mac can't use it.

Pass a device through

In the VM's window, click USB in the toolbar. The USB Passthrough list shows the USB devices plugged into the Mac. Switch a device on to attach it, and off to detach it. The first time, macOS may ask whether to allow it: see USB accessory access.

In Terminal:

mvz usb list homeassistant                 # the devices it can see, and what each is to the VM
mvz usb attach homeassistant 10c4:ea60     # attach now, and whenever the VM runs
mvz usb detach homeassistant 10c4:ea60     # detach, and stop attaching it

Name a device as list shows it: by its name or part of it, vid:pid, or vid:pid:serial. A name that fits several devices is refused, with the ones it fits. attach and detach need the VM running; list, remember and forget work while it's stopped. Every usb command takes --json. See USB devices in the CLI reference.

Remembered devices

A device you switch on is remembered: MacVisor attaches it whenever the VM runs and the device is plugged in, with the VM's window open or not, a VM started at login included. After you unplug and plug it in again, or the guest resets it, it's attached again. A failed attach is tried again after 2, 5, 15, 30 and 60 seconds; if it still fails, plug the device in again.

  • For this run only: mvz usb attach <vm> <device> --once. The window's switch always remembers.
  • Off for now, still remembered: mvz usb detach <vm> <device> --once. The device stays detached until it's plugged in again or the VM starts again.
  • Remember without attaching, also while the VM is stopped: mvz usb remember <vm> <device>. A device that isn't plugged in can be remembered by vid:pid or vid:pid:serial. mvz usb forget undoes it.
  • VM Settings → Advanced → USB Devices lists the remembered devices. Remove Device (the minus button) stops MacVisor attaching one; if it's attached now, it stays attached until the VM stops, or until you switch it off in the window.
  • The Overview's USB Devices card, while the VM runs, shows each remembered device's state, such as Attached, Not plugged in, Couldn't attach; trying again or Detached for now, and why one couldn't be attached.
  • Identical devices without serial numbers, such as two of the same adapter, are told apart by the USB port they were remembered on, so keep them on the same ports. A device with a serial number is found on any port.

For a VM that needs its devices from the moment the Mac starts, remember them once and turn on Start at Login. See Always-on host.

USB accessory access

MacVisor passes devices through with Apple's AccessoryAccess framework, new in macOS 27, which Apple lets MacVisor use through its USB accessory access entitlement. macOS itself takes the device from the Mac and hands it to the VM, and it may ask first whether to allow the accessory for MacVisor VM, the app that runs VM windows. Allow it and the attach goes on; mvz usb attach waits up to a minute for your answer. The dialog appears on the Mac's screen, so on a Mac you reach only over SSH, answer it over Screen Sharing.

Because macOS may ask at any time, a running VM with remembered USB devices, or devices attached for this run, keeps an icon in the Dock, even with no window open and when it started at login. Click the icon to open the window. Quitting it doesn't stop the VM: to quit it, shut the VM down. Other VMs run in the background with no Dock icon.

Which devices work

  • Devices the guest has a driver for, such as security keys, serial adapters, radios and USB drives. MacVisor doesn't filter devices by kind.
  • Not devices with isochronous endpoints, such as audio devices and webcams: Apple's Virtualization framework doesn't support them. The window's list marks such a device as not supported, and its switch can't be turned on.
  • One VM at a time. A device attached to a VM isn't available to the Mac or to other VMs until that VM lets it go.

Suspend, snapshots and copies

  • Suspend and live snapshots detach the VM's USB devices, and MacVisor attaches them again as soon as the VM runs. The guest sees them unplugged and plugged in again: a radio drops for a few seconds, and a security key's session ends. A device another VM took in the meantime stays with it, and the VM's events say what was detached and what came back. Revert & Resume of a snapshot taken while the VM was suspended attaches again what that suspend detached.
  • A device that won't detach refuses a suspend or a live snapshot you ask for, and nothing is saved. The suspend at logout or shutdown goes ahead anyway.
  • Pause and disk-only snapshots leave devices attached.
  • Restart from MacVisor attaches the remembered devices again; one attached with --once isn't.
  • A copy or clone doesn't remember the devices its original remembers, so two VMs don't compete for one. A VM made from a template keeps the template's, unless another VM remembers them. An imported VM or a restored backup remembers none.

Disk images as USB drives

You can also attach an ISO or a disk image file on the Mac to a running VM as a read-only USB drive: VM → Attach Disk Image… in its window, Attach Disk Image… on the Overview's USB Mass Storage card, or mvz usb attach <vm> --image <path>. See Disk images on a running VM.

If a device doesn't attach

  • Look at the Overview's USB Devices card for the reason, and at the VM's Runner Log, where USB lines start with [USB].
  • Couldn't attach; plug it in again to retry: unplug the device and plug it in again.
  • If another VM has the device, detach it there first.
  • If nothing happens, check the Mac's screen for macOS's question about the accessory.