Apple Deprecated hdiutil in macOS 27. If You Ship a .dmg, Your Release Script Is on Notice.
The man hdiutil page in the macOS 27 Golden Gate beta now opens with a deprecation notice. Apple's wording: "In macOS 27.0, hdiutil is deprecated. Use diskutil image instead for all disk image operations." If you distribute a Mac app outside the App Store, something in your release pipeline calls hdiutil. Probably a shell script you wrote once, got working, and have not opened since.
Deprecated is not removed. Nothing breaks on day one. That is exactly why this is worth ten minutes now rather than an afternoon during a release.
What Apple actually replaced
diskutil image picks up subcommands for attach, create, resize, info, and chpass. Most hdiutil options survive under different names, and the man page carries a deprecation notice listing the mappings. ASIF, Apple's sparse image format, is only supported by diskutil image and never worked in hdiutil at all, so the new tool is not purely a rename.
Jeff Johnson, who ships Mac apps and once worked on Knox, an app that calls hdiutil directly, ran both against the same job: a full encrypted disk image of a user home folder. The numbers are not close. hdiutil averaged 110 to 115 seconds. diskutil averaged 40 to 45 seconds. The resulting image was smaller too, 2.8 GB against 2.89 GB.
So the replacement is better. That is not the problem.
The flags that did not make it
Some options have no equivalent. The one that matters for automation is -puppetstrings, which emits progress output designed to be machine-parsed, including a -1 percentage meaning "this will take an indeterminate amount of time." If you have a build server that reads hdiutil progress, that reader has nothing to parse. diskutil does update a percentage in place, which is a partial substitute if your consumer is a human watching a terminal and no substitute at all if it is a script.
The create -srcfolder flags are the other gap:
-[no]crossdev -[no]scrub -[no]anyowners -skipunreadable -[no]atomic -copyuid
-scrub is the interesting one, because its absence is not neutral. In Johnson's comparison the hdiutil image contained ~/.Trash/, the diskutil image did not. diskutil behaves as though scrubbing is always on. If you were relying on -noscrub to capture temporary state, you no longer can, and nothing in the output tells you that a directory went missing.
The failure mode nobody will document for you
Here is the part I would actually get bitten by. Johnson's source folder contained a file owned by root, one of those group.com.apple.secure-control-center-preferences plists macOS drops in your Library. hdiutil hits it, logs an ownership warning, prompts for admin credentials, and finishes successfully after you authenticate.
diskutil does not prompt. It prints [100% completed] and then:
Error: Failed to create disk image: The operation couldn't be completed. Operation not permitted
That is the entire error, with --verbose enabled. No path. No indication that a permission on one file out of hundreds of thousands is the cause. Johnson guessed the reason and deleted the file to confirm.
A release script that fails loudly with a useless message is worse than one that fails quietly, because you will spend the debugging time on the wrong layer. My first instinct on seeing "Operation not permitted" at 100% would be to check codesigning, then the notarization keychain, then disk space. Not file ownership inside the source tree.
Why I do not think "deprecated" means "you have time"
Apple's deprecation timelines for command-line tools are not published, and there is no stated removal release. The honest read is that hdiutil will keep working for years. I have watched enough deprecated macOS tooling linger to believe that.
The risk is not removal. It is that the CI image you build on gets bumped to macOS 27, hdiutil starts printing a deprecation warning to stderr, and something in your pipeline treats unexpected stderr output as a failure. That failure lands on a Friday when you are trying to ship a hotfix. Deprecation warnings are cheap for Apple to add and expensive for a one-person release process to absorb at the wrong moment.
Johnson also notes that both tools on Golden Gate still carry a bug he reported last year about inaccessible .bnnsir files from Siri's CoreSpeech. He filed it with reproduction steps, and Apple's response was to ask whether it still happens in the latest beta and to request an iOS sysdiagnose for a macOS bug. That is a useful calibration for how fast the new tool's rough edges will get sanded down.
What I would actually do
Three things, in this order, and none of them is "migrate to diskutil today."
First, find out what your pipeline actually calls. grep -rn "hdiutil" . across your build scripts, your Fastlane config, your Makefile, your GitHub Actions workflow, and any packaging tool you vendored. You are looking for the call site and the exact flags. Write them down somewhere that is not just the script, because the script is what will get rewritten.
Second, pin your macOS runner version explicitly. If your workflow says macos-latest, you have handed the timing of this migration to GitHub's image rollout schedule. Naming a version means the change happens when you decide it does.
Third, when you do migrate, migrate to diskutil and keep the hdiutil call in a comment above it, with the old flags intact. Not for sentiment. Because the first time your image comes out missing files or your build server stops seeing progress output, the diff between what you asked the old tool for and what the new tool accepts is the entire debugging session.
I am not moving my own packaging step this month. I am adding the version pin and a note in the repo, and I will revisit when macOS 27 ships to a runner I care about.
Where this could be wrong
Johnson tested one workflow, a home-folder backup, not app distribution. Creating a .dmg from a small, staged, already-permission-clean folder is a much narrower operation than imaging a whole home directory, and most of the flags in the missing list are irrelevant to it. If your packaging step is hdiutil create -volname X -srcfolder staging -ov -format UDZO out.dmg against a directory you build fresh every time, the migration is probably a one-line change and you will never meet the root-ownership failure at all.
The counter-argument to my caution is also fair: Apple deprecated a tool and shipped a faster replacement that keeps the functionality. That is the good version of this. My objection is narrower, that the error reporting is not yet good enough for something sitting in an unattended pipeline, and that is a fixable complaint rather than a structural one.
Author
Lukas
@lukcombinator