Guest OS

• 1: Linux
• 2: macOS
• 3: Windows
• 4: FreeBSD

1 - Linux

Linux is the default guest operating system.

See also

• Templates

2 - macOS

Running macOS guests is experimentally supported since Lima v2.1.

• macOS only
• With Homebrew

limactl start template:macos

limactl start template:homebrew-macos

The user password is randomly generated and stored in the ~/password file in the VM. Consider changing it after the first login.

limactl shell macos cat /Users/${USER}.guest/password

Difference from Linux guests

• Password login is enabled
• Password-less sudo is disabled, except for /sbin/shutdown -h now (see Sudo — this is not currently configurable on macOS)
• Several features are not implemented yet. See Caveats below.

Advanced topics

Suppressing first-login setup screens

By default, macOS shows a series of setup wizard screens (Setup Assistant / mini-buddy) on the first GUI login. For automated or headless-style macOS VMs this is inconvenient. Set osOpts.Darwin.suppressFirstLoginSetup to have Lima pre-populate the relevant preference plists during provisioning, before any GUI session starts, so the setup screens are skipped automatically:

osOpts:
  Darwin:
    suppressFirstLoginSetup: true

This writes com.apple.SetupAssistant.plist into the guest user’s home directory and pre-configures com.apple.SoftwareUpdate system preferences so that the “Update Mac Automatically” dialog is also suppressed. The preferences are written as root (via the Lima guest agent) before first login, so macOS reads them as the authoritative initial state and does not reset them.

Default: unset — setup screens are shown as normal.

Custom plist

The built-in com.apple.SetupAssistant.plist template is shown below. At VM creation time, <build> is replaced with the output of sw_vers -buildVersion and <version> with sw_vers -productVersion from inside the guest. The version stamps are what macOS checks to decide whether setup is already complete — without them macOS resets MiniBuddyLaunchReason to 13 on first GUI login.

osOpts:
  Darwin:
    suppressFirstLoginSetup: true
    suppressFirstLoginSetupPlist: |
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <dict>
      	<key>DidSeeAccessibility</key><true/>
      	<key>DidSeeActivationLock</key><true/>
      	<key>DidSeeAppStore</key><true/>
      	<key>DidSeeAppearanceSetup</key><true/>
      	<key>DidSeeApplePaySetup</key><true/>
      	<key>DidSeeCloudSetup</key><true/>
      	<key>DidSeeLockdownMode</key><true/>
      	<key>DidSeePrivacy</key><true/>
      	<key>DidSeeScreenTime</key><true/>
      	<key>DidSeeSetupSequence</key><true/>
      	<key>DidSeeSiriSetup</key><true/>
      	<key>DidSeeSyncSetup</key><true/>
      	<key>DidSeeSyncSetup2</key><true/>
      	<key>DidSeeTermsOfAddress</key><true/>
      	<key>DidSeeTouchIDSetup</key><true/>
      	<key>DidSeeiCloudLoginForStorageServices</key><true/>
      	<key>LastPreLoginTasksPerformedBuild</key><string><build></string>
      	<key>LastPreLoginTasksPerformedVersion</key><string><version></string>
      	<key>LastSeenAgeRangeSelectionProductVersion</key><string><version></string>
      	<key>LastSeenBuddyBuildVersion</key><string><build></string>
      	<key>LastSeenCloudProductVersion</key><string><version></string>
      	<key>LastSeenDiagnosticsProductVersion</key><string><version></string>
      	<key>MiniBuddyLaunchReason</key><integer>0</integer>
      	<key>MiniBuddyShouldLaunchToResumeSetup</key><false/>
      	<key>SkipExpressSettingsUpdating</key><true/>
      	<key>SkipFirstLoginOptimization</key><true/>
      </dict>
      </plist>

When suppressFirstLoginSetupPlist is supplied, it is used verbatim — no <build>/<version> substitution is performed. Copy and adapt the built-in template above, then supply the actual build and version strings for your target OS release if needed.

Caveats

• No support for turning off the video display.
• No support for automatic port forwarding. Use ssh -L to manually set up port forwarding, or, use the vzNAT network to access the guest by its IP.
• No support for installing custom caCerts

Plain mode

containerd and automatic port forwarding are not available on macOS guests regardless of the mode, so plain mode additionally disables only the host directory mounts.

3 - Windows

Running Windows guests is experimentally supported since Lima v2.2.

• Windows 11
• Windows server 2025

limactl start template:windows

limactl start template:windows-2025

The user password is randomly generated and stored in the %USERPROFILE%\password.txt file in the VM. Consider changing it after the first login.

By default, Windows 11 enables Trusted Platform Module (TPM) emulation because of the hardware requirement. However, you can turn it off (in that case, lima bypasses the hardware check). In order to use TPM emulation, you need to install swtpm on your host computer.

For Windows server 2025, TPM emulation is disabled by default. However, there are some benefits if you enable TPM emulation. For example, you can install BitLocker disk encryption on your VM.

Difference from Linux guests

• Several features are not implemented yet. See Caveats below.

Caveats

• For Windows 11 guest, you need to download the installer ISO manually from here
• QEMU is the only VM driver that supports Windows guests
• provision feature is limited support (no boot, yq modes, and data and dependency modes have limitations)
• Only plain mode is supported (no file mount, no dynamic port-forwarding)
• Booting Windows 11 may occasionally fail. If it fails, please delete the instance and try it again from scratch.

4 - FreeBSD

Running FreeBSD guests is experimentally supported since Lima v2.1.

• FreeBSD 15
• FreeBSD 16 (CURRENT)

limactl start template:freebsd-15

limactl start template:experimental/freebsd-16

Prerequisites:

• QEMU
• xorriso (on non-macOS hosts)

Difference from Linux guests

• Several features are not implemented yet. See Caveats below.

Caveats

• No support for automatic port forwarding. Use ssh -L to manually set up port forwarding.
• No support for installing custom caCerts
• And more

FreeBSD prior to 15.1

• No support for mounting host directories. Use limactl cp or limactl shell --sync to share files with the host.

Plain mode

The guest agent, containerd, and automatic port forwarding are not available on FreeBSD guests regardless of the mode, so plain mode additionally disables only the host directory mounts (on FreeBSD 15.1 and later).