Build Bootable macOS Installer ISO/DMG from Apple Servers with mkmaciso

1. Overview

• This project provides a streamlined way to build bootable macOS installer media directly from Apple’s servers, with no Mac hardware required. It comprises two complementary components designed to simplify the creation and deployment of macOS installers.
• Part A is a self-contained script called mkmaciso. It uses only macOS built-in tools and commands to fetch the complete macOS installer from Apple, install it into the /Applications directory, and then generate bootable ISO or DMG images suitable for virtualization, USB installation, or other deployment scenarios.
• Part B offers GitHub Actions workflows that can run mkmaciso in cloud-hosted macOS environments (Azure datacenter-hosted Mac minis). This enables users without a physical macOS device to build installer media automatically, directly from a GitHub workflow.
• The project emphasizes accessibility and reproducibility, providing a path to produce both ISO and DMG formats to cover virtual machines, USB installers, and various virtualization platforms.

1. Disk Image Formats

• ISO images

• Best for virtual environments and VM-centric workflows. ISO files behave like a conventional CD/DVD image, making them convenient to attach to virtual machines as a virtual DVD.

• VM compatibility and mounting: In many virtualization platforms (Proxmox, QEMU, VirtualBox, VMware), ISO files are recognized as install media. On some systems, Windows can mount the ISO so you can inspect its contents if needed.

• Layout and structure: ISO images are designed as hybrid UDF/HFS configurations that enable broad compatibility with VM CD/DVD optical drive emulation.

• Practical notes: They reliably boot in VM environments and can serve as a portable, vendor-agnostic installer medium across different virtualization platforms.

• DMG images

• Best for bootable USB drives and direct physical installation scenarios.

• USB creation workflow: Use common disk-creation tools such as Rufus on Windows, dd on Linux, or asr on macOS to flash a DMG to a USB stick to create a bootable installer.

• Virtualization compatibility: For VM use, DMG may be converted to .vhd or .vmdk formats when necessary (e.g., Hyper-V or VMware environments). However, some platforms can also consume the raw disk image directly depending on the tooling.

• File naming quirks: DMG files ship with a .img suffix (for example, macOS_Sequoia.dmg.img). This convention helps some tools locate the image without having to switch Explorer to “All files.” After extraction or mounting, the usable DMG content remains the primary bootstrap installer.

• Conversion and interoperability: If you need to use DMG-based content in certain VM environments, you can convert DMG to alternative formats such as VHD or VMDK using appropriate conversion tools or QEMU utilities.

1. Supported Versions

• The project aims to cover a broad historical and current spectrum of macOS releases. It is designed to work with macOS installers dating back to OS X Lion (10.7, released in 2011) through the latest macOS Tahoe (2025 timeframe).
• Representative versions include: Lion (10.7), Mountain Lion (10.8), Mavericks (10.9), Yosemite (10.10), El Capitan (10.11), Sierra (10.12), High Sierra (10.13), Mojave (10.14), Catalina (10.15), Big Sur (11.x), Monterey (12.x), Ventura (13.x), Sonoma (14.x), Sequoia (15.x), and Tahoe (16.x). The breadth of coverage ensures compatibility with a wide range of virtualization labs, testing environments, and offline installation scenarios.
• By supporting this breadth, users can maintain bootable installers for legacy deployments, development sandboxes, or classroom environments where multiple macOS versions must be provisioned efficiently.

1. How to use

• Don’t have macOS? Leverage GitHub Actions

• Visual guide: The project includes a visual guide GIF that demonstrates how to fork and run the workflow. Image reference: How to fork and run workflow GIF (URL provided in the source).

• Step-by-step approach: 1) Fork the repository to your GitHub account (requires a GitHub account). 2) Navigate to the Actions tab in your forked repository to view and manage workflows. 3) Enable the workflows by clicking the “I understand my workflows, go ahead and enable them” button. 4) Choose a workflow from the left-side menu:

  • Recovery ISO (recommended): Produces a small, fast recovery image—2 to 5 minutes build time—ideal for virtual machines and quick recovery scenarios.
  • Full Installer: Produces a complete offline installer image (5–18 GB) suitable for full offline installation; build times range from 5 to 60 minutes depending on the selected macOS version and environment. 5) Click “Run workflow” and configure inputs, including:
  • macOS version: Select a version such as Sequoia, Sonoma, or others supported by the workflow.
  • Image format: Choose iso for VM usage or dmg for bootable USB drives. 6) Kick off the workflow by clicking the green “Run workflow” button and wait for the build to complete. 7) After completion, reload the page, scroll to the Artifacts section, and click the artifact link to download (e.g., macOSSequoia15.7.4.iso). 8) Recovery ISO artifacts are packaged in a zip file and must be unzip before use.

• Practical context: This pathway enables users without physical Macs to still generate bootable macOS media by using cloud-hosted macOS runners.

• Already have macOS? Run mkmaciso locally

• Quick start (example):

  • Command to perform a quick run, substituting tahoe with any desirable macOS label: curl -s https://raw.githubusercontent.com/LongQT-sea/mkmaciso/main/mkmaciso | bash -s tahoe

• Full local usage:

  • Download the script first, then execute with explicit parameters: curl -O https://raw.githubusercontent.com/LongQT-sea/mkmaciso/main/mkmaciso chmod +x mkmaciso ./mkmaciso --help

• Interactive mode:

  • Running ./mkmaciso without arguments triggers an interactive menu, guiding you through the selections and media creation options.

• Context: These commands rely on macOS-native toolchains to fetch the installer and generate the selected image format, using only built-in OS utilities.

• General workflow notes

• For VM deployments, attach the resulting ISO as a virtual CD/DVD drive to boot the installer in the virtual environment.

• For high-performance VM setups (e.g., Proxmox), GPU passthrough and related optimizations can yield better graphical and install performance, though this depends on host hardware and configuration.

• Some users may combine this project with related OpenCore-based workflows or iGPU passthrough techniques for more advanced installation scenarios.

1. Tips

• VM-specific guidance

• ISO-based media is particularly friendly for VM deployment—attach as a virtual CD/DVD and boot from the ISO to perform the installation inside the VM.

• GPU passthrough considerations can improve experience in Proxmox or similar hypervisors, especially when running GUI-based installers or post-installation environments.

• If you’re exploring further customization, you might look at related repositories such as OpenCore-ISO for bootstrapping macOS in VM contexts or Intel iGPU passthrough for enhanced graphical acceleration.

• USB and data partitioning

• When using DMG-based installers flashed to USB drives, you may notice leftover space on the drive after flashing. This space can be partitioned to host an EFI folder or other data as needed.

• If you’re using Linux’s dd utility to write the image to a device, always triple-check the target device to avoid catastrophic data loss. dd does not prompt for confirmation.

• Cross-tool workflows

• QEMU/Proxmox users can leverage raw disk images directly in some configurations, reducing the number of conversion steps.

• If you work with virtualization platforms that prefer VHD or VMDK formats, you can convert the ISO/DMG outputs using standard conversion tools to suit your environment.

• Related projects and ecosystems

• There is a broader ecosystem of related tools and repositories (such as OpenCore-ISO and Intel iGPU passthrough projects) that can help with more complex installation and bootstrapping scenarios.

1. Requirements for mkmaciso

• macOS 10.9 or newer (11+ recommended for better stability and features)
• An Intel-based Mac is preferred for broad compatibility; Apple Silicon can be used but may have some limitations
• 20–40 GB of free disk space during the build process to accommodate the installer components and output media
• Reliable internet connectivity to fetch installers directly from Apple’s servers
• Sufficient sudo privileges to perform system-level operations required by the installer creation process
• A functioning shell environment and standard macOS command-line tools that are already present on a typical macOS installation

1. Credits

• Apple Inc. for macOS and the official update servers that host the installer images.
• Mavericks Forever, for documenting the Mavericks recovery workflow and sharing knowledge relevant to macOS recovery protocols.
• InsanelyMac community, whose research into downloading macOS directly from Apple’s catalog provided foundational insights for this project.
• The repository maintainers and contributors who compiled, documented, and tested the mkmaciso workflow to enable others to build installers without requiring dedicated Mac hardware.

1. Legal and licensing

• This tool downloads macOS installer images directly from Apple’s official servers, and users are responsible for complying with Apple’s Software License Agreement.
• macOS is a trademark of Apple Inc.
• The project is licensed under GPLv3, ensuring that users have freedom to study, modify, and distribute the software in compliance with the license terms.

1. Images and visual references from the Input

• Visual guide for forking and running the workflow (GIF)
• Image reference: How to fork and run workflow GIF
• Source: https://raw.githubusercontent.com/LongQT-sea/macos-iso-builder/main/.github/howtoforkandrun_workflow.gif
• Context: The GIF offers a quick, visual walkthrough of how to fork the repository and enable and run the GitHub Actions workflows, providing a practical companion to the written instructions.
• Release page and related documentation
• The original input references a Release page where users may find pre-built artifacts or alternative configurations. This resource serves as a navigational cue for users to verify if pre-built options already exist or to obtain additional context about releases.
• Repository links and project ecosystem
• Various URLs included in the input (for example, the macOS ISO builder repository and related OpenCore/Intel iGPU passthrough projects) act as anchors for users seeking deeper dives into related tooling and advanced installation strategies.
• Practical notes on usage
• The input emphasizes practical steps and configurations through textual references and links. These references are included to ground the description in real-world usage scenarios and to point readers toward practical artifacts (e.g., artifacts in GitHub Actions, downloadable ISO/DMG outputs).

End of description.