Skip to content

[FR] - Add 'create' options to utmctl to facilitate creating VM's from command line #6092

Closed

Description

@redtrinity

I've been trying to create macOS guest VM's on macOS (host) with the scripts as documented here and with various settings documented in the reference guide here however when creating macOS guests they always default to a linux type, and there are no means of scripting the "attachment" of an ipsw file to use. Displays also can't be added/managed.

It would be very helpful if the utmctl tool could take a create argument that could also be supplied other sub arguments like type, display, serial, ipsw, iso, etc, etc.

For example:

[foo@example]: ~# /Applications/UTM.app/Contents/MacOS/utmctl create --type apple --arch aarch64 --ipsw "/Users/foo/Desktop/macOS/macOS_Sonoma_14.ipsw" --display 1920x1200@80 --interface en0 --network-mode bridged --mac-addr ff:ff:ff:ff:ff:ff --os macOS --cpu-count 1 --memory 8092 --entropy --audio --keyboard Mac --pointer Trackpad

This isn't the specific type of command structure that this should take nor representative of all possible options, but just an example.

It would also be really helpful if the create argument could take an optional --config-file type argument where a YAML/json/TOML file could be provided that would inform utm of all the parameters to use to create the virtual machine.

This would be incredibly helpful for automating VM creation for automating spinup of new VM's to test macOS.

Activity

  1. added this to the Future milestone on Feb 26, 2024
  2. meisenbarth commented on Sep 11, 2026

    @meisenbarth
    Contributor

    We hit this from the macOS side and have a working implementation, opened as two PRs: #7862 (create a macOS VM from a script) and #7863 (install it without the GUI confirmation sheet).

    Some context on what we found, since it is narrower than the original request: the scripting layer already has a create command and it already handles the Apple backend. createAppleVirtualMachine honours name, memory, CPU count and drives — everything in the record flows through UTMScriptingConfigImpl.updateConfiguration(from:). The one thing that cannot be asked for is the operating system:

    config.system.boot = try UTMAppleConfigurationBoot(for: .linux)   // always Linux

    UTMAppleConfigurationBoot.init(for:) already takes an OperatingSystem, so a scripted macOS VM is a few lines rather than a feature.

    Three things we got wrong at first, in case they save someone else the time:

    • We assumed macRecoveryIpswURL having no CodingKey was an oversight. It isn't — the IPSW is persisted in the registry via updateRegistryFromConfig / updateConfigFromRegistry. Nothing needs changing there.
    • Setting the OS and the IPSW alone is not enough. fillVZConfiguration throws platformUnsupported for a macOS guest with no macPlatform, so the VM is created and then refuses to run. The hardware model has to be derived from the caller's IPSW.
    • A scripted macOS guest also needs a display. The scripted create clears displays (the headless-by-default convention that suits Linux), and fillVZConfiguration only builds a graphics device when displays is non-empty — so the guest booted to 0% CPU with nothing to render into. scripting: allow creating macOS VMs with the Apple backend #7862 gives a macOS guest the wizard's default display unless the caller specifies one.

    Both PRs are built against main (Xcode 26.6, Apple Silicon) and verified end to end: a macOS 26.6.2 guest created, installed and booted to Setup Assistant in a UTM display window, entirely from AppleScript.

    On the confirmation sheet: #7863 does not remove it. It guards a drive-erasing action and GUI users should keep it. It is also structurally unavailable to a script — showConfirmAlert needs a window, and the scripted start path is what raises it. A separate install verb that goes straight to installVM(with:) never opens a window, so the sheet never arises; asking for install is the confirmation. That seemed to fit the note in CONTRIBUTING.md about putting things most users do not need into the scripting interface rather than the UI.

  3. modified the milestones: Future, v5.0 on Sep 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions