mkmaciso: macOS ISO Builder — Create Bootable Images
/macos-iso-builder
mkmaciso does exactly one thing well: it turns Apple's software catalogs into bootable images you can actually use. If you run Hackintosh setups, need a macOS VM on Proxmox or VMware, or maintain installation media across many macOS versions, this script saves hours of manual fetching and packaging. The GitHub Actions path removes the Mac hardware requirement entirely. Skip it if you only ever need the latest macOS installer once and can download it normally — the workflow overhead isn't worth a one-off.
What is mkmaciso?
mkmaciso is a shell script that downloads the full macOS installer from Apple's servers and packages it into a bootable disk image — ISO for virtual machines or DMG for USB drives. The script uses only macOS built-in tools (asr, hdiutil) and requires no third-party utilities. If you do not have access to a Mac, the repository includes GitHub Actions workflows that run the script on hosted Mac mini runners, letting anyone with a GitHub account build installer images for free.
What mkmaciso builds — formats, versions, and sources
- ✓Downloads macOS installers directly from Apple's update servers — no Apple ID or manual browsing required
- ✓Builds two formats: ISO (hybrid UDF/HFS layout, attaches as virtual DVD for Proxmox/QEMU/VMware) and DMG (raw GPT image, flashable to USB with dd or Rufus)
- ✓Supports every consumer macOS release from OS X Lion (10.7) through macOS 26 Tahoe, including Lion, Mountain Lion, Mavericks, Yosemite, El Capitan, Sierra, High Sierra, Mojave, Catalina, Big Sur, Monterey, Ventura, Sonoma, Sequoia, and Tahoe
- ✓GitHub Actions workflow offers a free, no-Mac build path using Azure-hosted Mac minis — pick Recovery ISO (2-5 minutes) or Full Installer (5-60 minutes)
- ✓Recovery ISO artifacts are intentionally small and fast to produce, designed for VM testing
- ✓DMG output carries a .img suffix so Rufus on Windows recognizes it without switching file type filters
- ✓Fully scriptable — pass a version name (tahoe, sonoma, etc.) as a command-line argument or run interactively
- ✓Licensed under GPLv3, script source fully readable on GitHub
Virtual machines vs bootable USB drives
- •Proxmox VE or QEMU homelab — attach the ISO as a virtual CD drive, boot the VM, and install macOS without any conversion step
- •VMware Workstation or Fusion — mount the ISO directly or convert the DMG to VMDK with qemu-img for ESXi use
- •Bootable USB for Hackintosh builds — flash the DMG to a USB drive, then partition the remaining space for your EFI folder
- •Hyper-V users — convert the DMG to VHD using qemu-img before attaching the virtual hard disk
- •CI/CD pipelines — fork the repo, trigger a workflow, and download the artifact minutes later for automated testing
- •Archiving old macOS versions — the tool covers every major release back to Lion, useful for vintage Mac recovery scenarios
Running mkmaciso locally on macOS
On macOS, a one-liner in Terminal fetches and executes the script directly from GitHub without cloning the repo: `curl -s https://raw.githubusercontent.com/LongQT-sea/mkmaciso/main/mkmaciso | bash -s tahoe`. Swap tahoe for any supported version name. To inspect the script first, download it with `curl -O` and make it executable with `chmod +x mkmaciso`, then run `./mkmaciso` for an interactive menu. No Homebrew, no dependencies beyond what macOS ships.
Building macOS images via GitHub Actions
Fork the repository, enable GitHub Actions in the Actions tab, and select a workflow from the sidebar. Recovery ISO is the fastest option (2-5 minutes) and produces a small image sufficient for VM installations. Full Installer takes longer (5-60 minutes) and generates a complete offline installer (5-18GB). Choose the macOS version and image format (iso or dmg), then click Run workflow. When the run completes, scroll to the Artifacts section — the download link appears after reloading the page. Recovery ISO artifacts are zipped and must be unzipped before use.
Strengths
- ✓No Mac hardware required — builds bootable macOS installer images entirely through GitHub Actions, using Azure-hosted Mac minis as runners.
- ✓Two output formats cover different use cases: ISO (hybrid UDF/HFS layout, works as a virtual DVD in Proxmox, QEMU, VMware) and DMG (raw GPT, flashable to USB or convertible to VHD/VMDK).
- ✓Covers OS X Lion (10.7) through macOS Tahoe (26) — useful if you need legacy macOS versions that Apple no longer distributes publicly.
- ✓Check the Release page first — pre-built images may already exist for your version, letting you skip the build step entirely.
- ✓Local macOS use requires only a single curl pipeline into bash; no dependencies beyond what macOS ships with since 10.9.
Hardware requirements and Apple Silicon caveats
- △Apple Silicon support is explicitly marked as having "some limitations" — the README doesn't specify what breaks or how badly, so you may hit silent failures depending on your Mac and the target macOS version.
- △The "no Mac required" claim only applies to the GitHub Actions path. Running `mkmaciso` locally still requires macOS 10.9+ (11+ recommended), sudo access, and 20–40 GB of free disk space during the build.
- △GitHub Actions uses free Azure-hosted Mac mini runners — the README itself warns to use them responsibly, which hints at real rate-limiting or access-restriction risk for anyone building frequently or large images.
- △DMG output needs conversion for Hyper-V (.vhd) or VMware (.vmdk) use; only QEMU and Proxmox accept the raw disk image directly, adding a step if your VM platform isn't one of those two.
- △Recovery ISO artifacts are delivered as zip files — you must unzip before mounting, and the README gives no size estimate for how long that step takes on large images.
Other ways to create macOS installer images
Frequently asked questions
mkmaciso downloads directly from Apple's update servers, the same source a Mac uses. It is the user's responsibility to comply with Apple's Software License Agreement. The tool itself carries no special permission — it automates a manual process, but the legality of that process depends on your license terms, not the tool.
Yes. The script is open source under GPLv3, and the GitHub Actions build path uses free hosted runners. There is no cost unless you choose to run builds on your own Mac hardware or self-hosted runners.
Apple Silicon support exists but the project describes it as experimental. Intel Macs are the recommended platform for running the script locally. If you are on an M-series Mac, the GitHub Actions workflow is the more reliable path.
The ISO format attaches directly to Proxmox, QEMU, and VMware as a virtual DVD. For Hyper-V, convert the DMG to VHD using qemu-img. For VMware Workstation or ESXi, convert the DMG to VMDK with qemu-img.
The script covers OS X Lion (10.7) through macOS 26 Tahoe. Every consumer release from Lion to the current version is explicitly listed as supported, including Mavericks, Yosemite, El Capitan, Sierra, High Sierra, Mojave, Catalina, Big Sur, Monterey, Ventura, Sonoma, Sequoia, and Tahoe.
No. The GitHub Actions workflow runs on Azure-hosted Mac minis and is free for public repositories. Fork the repo, enable Actions, pick a workflow and macOS version, and download the finished ISO or DMG from the Artifacts section without touching a Mac.
Who should try it — and who should skip
Reach for mkmaciso if you run Proxmox, QEMU, or VMware on non-Apple hardware and need reliable macOS VM images, or if you maintain Hackintosh installations and want a repeatable way to build fresh installer media without a Mac. homelab operators and CI/CD pipelines benefit most from the GitHub Actions path. Skip it if you have a real Mac and just need the occasional installer — the official App Store download is faster. Skip it too if you need Apple Silicon native performance; the experimental ARM support is not the recommended path.
Related repositories
Still deciding about macos-iso-builder?
One click hands the question to an AI along with this page — see what it says about macos-iso-builder.