macos-iso-builder: build macOS installer ISOs and DMGs from Apple's servers without a Mac

The gap macos-iso-builder fills: no Mac in the room

Apple distributes macOS installers as applications and recovery images, not as ISO files. If you want to boot macOS in Proxmox, QEMU or VMware, or write installation media from a Windows or Linux workstation, you have to convert what Apple serves into a disk image those tools accept. That conversion normally needs a running Mac, which is exactly what someone building a Hackintosh or a virtualized macOS lab does not have yet.

macos-iso-builder splits the problem in two. The mkmaciso shell script does the download and image creation on a Mac, using only built-in macOS tools and commands, per the README. The GitHub Action workflows run that same script on Azure datacenter-hosted Mac minis, so a GitHub account substitutes for the hardware. The stated version range runs from OS X Lion (10.7, 2011) to macOS Tahoe (26, 2025), which matters because old installers are the hardest to obtain through normal channels.

ISO versus DMG: two output formats with different jobs

The README is explicit that the two formats are not interchangeable. ISO files use a hybrid UDF/HFS layout and are meant to be attached to a VM as a virtual DVD; the README notes they will even mount in Windows. DMG files are raw GPT disk images intended for flashing to a USB drive with Rufus on Windows, dd on Linux, or asr on macOS. For VM use, the README suggests converting a DMG with qemu-img to .vhd for Hyper-V or .vmdk for VMware, while QEMU and Proxmox can consume the raw disk image directly.

One quirk is worth knowing before you go looking for the file: DMG artifacts ship with a .img suffix, for example macOS_Sequoia.dmg.img, so that Rufus finds them without the user switching Explorer to "All files". If you script around these downloads, match on that suffix rather than on .dmg.

How the GitHub Actions path works, and what it costs you

The mechanism is a fork-and-run loop rather than a hosted service. You fork the repository, open the Actions tab, and click the button that enables workflows in your fork. Two workflows are offered in the sidebar. Recovery ISO is described as a small recovery image that builds in 2 to 5 minutes and is recommended for VMs. Full Installer produces a complete offline installer of 5 to 18GB and takes 5 to 60 minutes to build.

Each run takes two inputs: the macOS version (Sequoia, Sonoma, and so on) and the image format, iso for virtual machines or dmg for bootable USB drives. When the run finishes you reload the page and download from the Artifacts section, for example macOS_Sequoia_15.7.4.iso. Recovery ISO artifacts arrive zipped and must be unzipped first.

The cost is other people's infrastructure. The README carries an explicit note that GitHub-hosted runners are a free public resource and asks users to be responsible with them. That is a social constraint, not a technical one, and it is the main reason to prefer the local script when you already have a Mac.

Running mkmaciso locally on an existing Mac

If you do have macOS, the script avoids the fork entirely. The README's quick run pipes the script from the repository into bash and passes the version as an argument, with tahoe as the example. Change that word to the release you want.

curl -s https://raw.githubusercontent.com/LongQT-sea/mkmaciso/main/mkmaciso | bash -s tahoe

The README also shows downloading the script first so you can inspect it and use the flag interface. This is the safer order for anything that runs with sudo.

curl -O https://raw.githubusercontent.com/LongQT-sea/mkmaciso/main/mkmaciso
chmod +x mkmaciso
./mkmaciso --help

Running ./mkmaciso with no arguments opens an interactive menu instead. Note the argument syntax differs between the two paths: the piped form passes the version after bash -s, while the downloaded script is invoked directly.

Requirements are listed as macOS 10.9 or newer, with 11+ preferred, an Intel Mac recommended, 20-40GB of free space during the build, an internet connection and sudo access. The script downloads the installer into /Applications before creating images, so that space requirement is not optional. Apple Silicon is supported but the README states it comes with limitations without enumerating them, which is a gap worth testing against your own machine before you plan around it.

Where macos-iso-builder is the wrong tool

The README documents no checksum, no signature verification and no provenance file for the images it produces. You are downloading an installer from Apple's servers through a third-party script and then trusting the artifact your fork generated. On a public fork, anyone with commit access to that fork can change what runs. If your threat model includes a tampered installer, this pipeline gives you no verification step to point at, and the README does not claim one.

The GitHub Actions route is also unsuitable for repeatable automation. Workflows are triggered manually from the Actions tab, artifacts are downloaded by hand from the run page, and artifact retention is governed by GitHub's settings rather than by anything in this repository. There is no documented CLI or API for pulling a finished image into a CI job. If you need a nightly rebuild of a macOS image inside your own pipeline, this is not that.

Finally, the maintenance signal is unusual. The most recent releases are dated 2026-09-28, 2026-09-27 and 2026-09-26 and are titled "Recent Forks List", which suggests the release feed is tracking forks rather than shipping image builds. The last push to the repository was on 2026-09-28. Anyone expecting versioned image releases with changelogs should read the release page before assuming that is what they are.

Alternatives and the actual difference in approach

The README points to a sibling project, OpenCore-ISO, for installation help, and to intel-igpu-passthru for Intel iGPU passthrough on Proxmox. Those are complements, not substitutes: they handle booting and hardware passthrough, while macos-iso-builder only produces the installer image.

The closer alternative is the manual route documented by the InsanelyMac community, which the credits cite for research on downloading macOS directly from Apple's catalog, along with Mavericks Forever for the Mavericks recovery protocol. That approach means running Apple's own installer tooling and conversion steps yourself on a Mac. It gives you full visibility into every command and lets you verify each stage, at the cost of writing and maintaining the conversion logic, including the older recovery protocols that differ by release. macos-iso-builder packages that logic behind one script and adds the hosted-runner path for people without hardware. The trade is convenience for a layer of indirection you cannot easily audit without reading the script.

For pure VM use, a plain recovery image attached as a virtual DVD is often enough, and the README recommends the Recovery ISO workflow for exactly that case. The full installer is for offline installation or USB media, and it is the expensive path at 5 to 18GB.

Licence, upgrade cost and what to check before you rely on it

The project is licensed under GPL-3.0, and the repository carries a LICENSE file at the top level alongside README.md, the .github directory and the mkmaciso script. GPL-3.0 matters if you plan to redistribute a modified mkmaciso or embed it in another product; the licence obligations attach to the code, not to the macOS images it produces. Those images remain governed by Apple's Software License Agreement, which the README links and which it says users are responsible for complying with. That is a factual boundary, not legal advice.

Upgrade cost is low in the ordinary sense: there is no package to install and no dependency graph, since the script relies on macOS built-in tools. The maintenance you inherit is watching Apple's catalog. When Apple changes how a given release is served, the script has to change with it, and the README's credits suggest that older releases needed separate research (the Mavericks recovery protocol is called out by name). If you pin your workflow to one macOS version, expect to re-run and re-verify when Apple retires or moves that installer.

What to verify first: whether the release page already has your version built, which of the two workflows matches your target (Recovery ISO for VMs, Full Installer for offline or USB), and how much free disk you have if you run mkmaciso locally, since the build needs 20-40GB and downloads into /Applications.

Editorial conclusion

Adopt it if you need a macOS installer image for Proxmox, QEMU, VMware or a USB stick and you either own a Mac or are willing to fork the repository and spend GitHub Actions minutes on a hosted Mac runner. Do not adopt it if you need a supported, Apple-blessed distribution channel or a signed, reproducible artifact with a published checksum: the README documents neither signing nor verification. Before your first build, read the release page to see whether someone already built your version, then check the two workflow names in the Actions tab, because Recovery ISO and Full Installer are not interchangeable and the full installer can take up to an hour.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. LongQT-sea/macos-iso-builder on GitHub
4. README
5. Releases