Creating macOS Virtual Machines
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu provides a streamlined workflow for creating and running optimized macOS virtual machines on Linux and macOS hosts. By leveraging quickget for automated image acquisition and quickemu for optimized hardware configuration, the project eliminates the need for manual QEMU configuration while ensuring "the right thing" is done for each specific macOS version.
The system supports a wide range of macOS releases and utilizes specific drivers and sharing protocols—such as VirtIO-9p and Samba—to ensure a high-performance guest experience. This module is a core component of the Quickemu project, sitting alongside support for Linux and Windows environments.
Sources: README.md:15-22, README.md:46-51
Supported macOS Versions
Quickemu currently supports a broad spectrum of macOS releases, ranging from legacy versions to the most recent updates.
| Version | Marketing Name |
|---|---|
| macOS 15 | Sequoia |
| macOS 14 | Sonoma |
| macOS 13 | Ventura |
| macOS 12 | Monterey |
| macOS 11 | Big Sur |
| macOS 10.15 | Catalina |
| macOS 10.14 | Mojave |
Sources: README.md:52-53
Architecture and Workflow
The creation of a macOS VM follows a two-step process involving distinct functional components within the Quickemu ecosystem.
1. Image Acquisition via quickget
The quickget script serves as the downloader and configuration generator. It fetches the required recovery or installation images from upstream sources and automatically generates a .conf file. This file contains the necessary parameters for the VM, such as the OS type and architecture.
Sources: README.md:31-33, AGENTS.md:5-7
2. Execution via quickemu
The quickemu script acts as the main VM launcher. It parses the configuration file created by quickget, enumerates the host hardware, and applies the optimum QEMU arguments for the specific macOS version. This includes setting up CPU topologies, memory allocation, and peripheral emulation.
Sources: README.md:34-36, AGENTS.md:5-7
The following diagram illustrates the interaction between the user, the Quickemu scripts, and the underlying QEMU system:
Sources: README.md:31-36, AGENTS.md:5-7
Core Features for macOS Guests
Quickemu implements several advanced features specifically tuned for macOS guests to improve usability and performance.
- File Sharing: Supports VirtIO-9p for high-speed file sharing between the host and macOS guests. Additionally, Samba file sharing is supported if
smbdis installed on the host. - Audio: Provides full duplex audio support.
- Networking: Includes automatic SSH port forwarding and general network port forwarding.
- Input/Output: Full SPICE support is included, enabling features like host/guest clipboard sharing.
- Architecture Support: Supports
x86_64andaarch64(ARM64) guests. ARM64 guests are native on Apple Silicon hosts and emulated via TCG onx86_64hosts.
Sources: README.md:54-72, AGENTS.md:73-77
Configuration Logic
The logic for creating a new OS entry, including macOS, is centralized in quickget. Developers adding or updating macOS support must interact with specific functions to define how versions are retrieved.
| Function | Purpose |
|---|---|
os_info() | A case statement determining the OS type. |
releases_macos() | Returns available macOS versions (e.g., Sequoia, Sonoma). |
arch_macos() | Defines supported architectures (e.g., amd64, arm64). |
| Download Logic | Constructs the URL to fetch the installer/recovery images. |
Sources: AGENTS.md:46-56
Development and Diagnostics
For developers maintaining macOS support within Quickemu, the project provides a structured environment and diagnostic tools.
- Linting: All scripts (Bash 4.0+) are validated using
shellcheckto ensure code quality and avoid regressions in the VM launching logic. - Diagnostics: The
quickreporttool is available to provide system diagnostics if a macOS VM fails to start or encounters performance issues. - Verification:
chunkcheckis used to verify the integrity of the downloaded macOS images.
Sources: AGENTS.md:7-11, AGENTS.md:27-30
Sources: AGENTS.md:27-41
Summary
Creating macOS virtual machines in Quickemu is designed to be an automated, "zero-config" experience for the end-user while maintaining a robust, scriptable backend for contributors. By partitioning the responsibilities between quickget (acquisition) and quickemu (execution), the project ensures that macOS guests are always provisioned with optimal hardware settings and modern features like VirtIO-9p sharing and SPICE integration.
Sources: README.md:23-28, AGENTS.md:5-7