Contents

Installing macOS on a Virtual Machine

Download a macOS restore image and install it in a new VM.

Overview

Each new VM begins in an empty state. To boot and run macOS in a VM, you must first install a macOS image onto the new VM. Installing macOS in a new machine requires the following steps:

  1. Obtain a restore image.

  2. Set up a compatible VM configuration.

  3. Create a VM, install the restore image, and start the VM.

Obtaining the Restore Image

A macOS restore image is an installation media file for a specific version of macOS. Use VZMacOSRestoreImage to find restore images over the network and obtain information about their requirements. To obtain a new restore image use the latestSupported class function to download the latest supported macOS image over from Apple the network using the URL in the restore image’s url property.

If you already have a restore image on disk, you can reload the VZMacOSRestoreImage from a local URL instead.

Setting up the VM Configuration

Running a macOS, VM requires a valid VZMacPlatformConfiguration, a VZMacOSBootLoader, and a configuration compatible with the VZMacOSRestoreImage.

A VZMacOSRestoreImage can contain installation media for multiple Mac hardware models (VZMacHardwareModel) and the current host may not support some of these hardware models. Use the mostFeaturefulSupportedConfiguration property to determine the hardware model and configuration requirements that provides the most complete feature set compatible with the current host. If the current hosts supports none of the hardware models, this property is nil.

The VZMacPlatformConfiguration configuration encapsulates all the necessary unique components for booting and running macOS on Apple silicon, these are:

  • The hardware model — A Mac platform configuration must describe the specific virtual Mac hardware model it targets. During installation this should match the hardwareModel of the VZMacOSRestoreImage.

  • Auxiliary storage — Auxiliary storage contains data used by the macOS boot loader and operating system and is necessary to boot a macOS guest OS. During installation this can be a newly created auxiliary image that uses the hardwareModel of the VZMacOSRestoreImage.

  • A machine identifier — A machine identifier that macOS guests use to uniquely identify the virtual hardware.

To configure the VZMacPlatformConfiguration for installation:

  1. Create a VZMacPlatformConfiguration.

  2. Set its VZMacPlatformConfiguration.hardwareModel to the VZMacOSConfigurationRequirements.hardwareModel.

  3. Create a new VZMacAuxiliaryStorage with init(creatingStorageAt:hardwareModel:options:) using the VZMacOSConfigurationRequirements.hardwareModel.

  4. Set the new VZMacAuxiliaryStorage on VZMacPlatformConfiguration.auxiliaryStorage.

Installing and Running the VM

Install a macOS using a VZMacOSInstaller with a VM instance and an image on the local filesystem using the following steps:

  1. Create a VZVirtualMachineConfiguration with a VZMacPlatformConfiguration configured as described above.

  2. Create a new VZVirtualMachine from the VZVirtualMachineConfiguration.

  3. Create a VZMacOSInstaller with the VZVirtualMachine and the image that you downloaded, either as a new image from Apple servers or using a previously saved image. The URL must the refer to a local file on disk.

  4. Call the installer’s install() to start the installation.

A VM must be in a VZVirtualMachine.State.stopped state to start installation. Pausing, or stopping the virtual machine during the installation process results in undefined behavior. You can monitor or cancel the installation progress by observing progress property of the VZMacOSInstaller.

The example below shows the complete process for installing and running a macOS VM:

See Also

Virtual machine setup