How to Use hdiutil in macOS

In June 2026, a build engineer at a mid-sized Mac software company ran the same release script they had used for eight years, and it showed a warning they had never encountered before. The script called hdiutil create -srcfolder to package a .dmg, and the terminal printed a line that stopped them mid-deploy: the tool was deprecated. They are not the only ones affected. Every CI pipeline, packaging script, and installer builder that still calls hdiutil now has a documented deadline, and the message appears directly in the hdiutil man page.

The notice is clear. Under a “DEPRECATION NOTICE” heading it states, in Apple’s own words, that hdiutil is deprecated in macOS 27 Golden Gate, and that diskutil image is the preferred interface. It then adds a line that turns a suggestion into a firm deadline: new features and formats, including the new ASIF (Apple Sparse Image Format), are available only through diskutil image. The old tool is not just discouraged; it cannot handle ASIF at all. macOS 27 Golden Gate ships in September 2026, and the deadline is already set.

Key Takeaways

hdiutil is deprecated in macOS 27 Golden Gate, with diskutil image identified as the preferred replacement interface.
The deprecation does not mean immediate removal: most hdiutil commands still work, but new formats and features are available only through diskutil image.
diskutil image provides subcommands for attach, create, resize, info, and chpass, corresponding directly to old hdiutil commands.
ASIF (Apple Sparse Image Format) images cannot be created or modified by hdiutil. This is a strict limitation, not a warning.
Any tool or script that parses hdiutil output or wraps it in a library should be reviewed now, before Apple removes the tool in a future release.

What the Deprecation Notice Actually Says

The deprecation is documented in the tool’s own man page, which is the official source for how Apple expects developers to interpret this change. The notice appears under a “DEPRECATION NOTICE” heading and states directly that for the listed commands, diskutil image is the preferred interface. It also says that new features and formats, such as ASIF, are available only through diskutil image.

Many people overlook that second sentence. A deprecation that only said “use the new tool” would be a gentle suggestion. The ASIF clause sets a firm deadline. Apple is not just encouraging developers to switch; it is releasing capabilities that the old command cannot handle. Once you need an ASIF image, hdiutil is not just discouraged; it cannot perform that task.

The Verb-by-Verb Migration Table

The man page includes a table that matches every hdiutil command to its diskutil replacement. This is the most useful reference for anyone migrating, because it removes uncertainty about which subcommand to use now. Here is the mapping, reproduced from the deprecation notice.

hdiutil verb	diskutil replacement
attach	diskutil image attach
create	diskutil image create blank
create -srcfolder	diskutil image create from
create -srcdevice	diskutil image create from
convert	diskutil image create from
resize	diskutil image resize
imageinfo	diskutil image info
partition	diskutil image info
pmap	diskutil image info
chpass	diskutil image chpass
detach	diskutil eject
unmount	diskutil unmount
mountvol	diskutil mount

Three patterns stand out in that table. First, the create command splits: a blank image becomes create blank, while copying a folder or device becomes create from. Second, three separate hdiutil commands (imageinfo, partition, and pmap) all map to a single diskutil image info. Third, the old detach command maps to diskutil eject, which is a change in approach: the replacement uses a disk-eject model rather than a dedicated detach command.

The ASIF Gap: What hdiutil Can No Longer Touch

The deprecation notice singles out one format by name: ASIF, Apple Sparse Image Format. The man page states clearly that ASIF images “are not supported by hdiutil” and “can only be created and manipulated using diskutil image.” This is the most significant part of the change, because it is not a future issue; it is a current limitation.

For teams that already build sparse images as part of their packaging or backup workflows, this matters immediately. The classic hdiutil create -type SPARSE and -type SPARSEBUNDLE formats (UDSP and UDSB in the underlying image-type codes) still work, but they are not ASIF. If Apple’s newer sparse format becomes the default for certain tools or workflows, any script still calling hdiutil will fail to read or write those files.

The diskutil man page describes the broader tool’s role clearly: it “manipulates the structure of local disks,” covering disk images, APFS volumes, CoreStorage volumes, and AppleRAID sets. The image subcommand is where disk-image management now happens, and it is the only way to handle ASIF. That consolidation is the main point: Apple is moving disk-image operations under the same tool that already manages volumes, partitions, and filesystems.

Scripting Impact: What Breaks in CI and Tooling

The deprecation affects people who automate macOS. hdiutil has been the main tool for tasks like creating a .dmg for a release artifact, mounting it to copy files, converting a .dmg to .cdr or .iso for burning, and resizing sparse images. Each of those has a direct replacement, but the replacement changes the command syntax, so every wrapper breaks.

Developer writing shell scripts for disk image automation — Most hdiutil usage is inside shell scripts and CI steps, which is where the migration effort is concentrated.

Consider the Go ecosystem. The go-darwin/hdiutil package wraps the hdiutil command for Go developers, and its repo metadata tells a cautionary story: it last received an update in 2019 and has 14 stars and a single fork. A wrapper that has not been updated in seven years will not gain diskutil image support automatically. Any project depending on it, or on similar wrappers in other languages, will need a fork or rewrite rather than a simple update.

Disk image storage hardware affected by deprecation

Most hdiutil usage is inside shell scripts and CI steps, which is where the migration effort is concentrated.

There are two types of breakage to consider. The first is mechanical: hdiutil attach image.dmg becomes diskutil image attach image.dmg, and the output format may change. The second is behavioral: because detach maps to diskutil eject and imageinfo maps to diskutil image info, scripts that parsed the old structured output need to be checked against the new tool’s output. The old attach output has been stable since Mac OS X 10.0 and is “intended to be program-readable,” according to the man page, a stability guarantee the replacement does not yet provide in the same terms.

The -plist and -puppetstrings flags deserve special attention. hdiutil has long provided -plist output for programs to parse, and -puppetstrings for progress parsing. Teams that built reliable automation on those flags need to verify whether diskutil image offers equivalent structured output. The diskutil man page documents -plist for commands like list and info, but the image-specific output format is newer and should be tested before relying on it in production.

Migration Code: Attach, Create, and Convert

The clearest way to plan a migration is to compare old and new commands side by side for tasks that actually run in production. The examples below use realistic filenames and follow the command mapping from the deprecation notice.

Attaching an image for inspection is the most common operation, and the migration is a straightforward prefix change.

# OLD: blank sparse image
hdiutil create -size 2g -type SPARSE -fs APFS ./cache.sparseimage

# NEW: blank image
diskutil image create blank -size 2g -fs APFS ./cache.sparseimage

# OLD: image from existing folder
hdiutil create -srcfolder ./payload -format UDZO ./payload.dmg

# NEW: image from existing folder
diskutil image create from ./payload -format UDZO ./payload.dmg

# Note: 'create from' also replaces 'create -srcdevice' and 'convert'.
# Verify -format and -type flags against diskutil image help,
# since image-type codes (UDZO, UDSP, UDSB) may be expressed
# differently in the new interface.

Converting a .dmg to .cdr for burning is a workflow Apple’s own documentation and third-party guides have recommended for years. The replacement uses the create from subcommand.

# OLD: convert DMG to burnable CDR/ISO
hdiutil convert ./input.dmg -format UDTO -o ./output.iso

# NEW: conversion through 'from' subcommand
diskutil image create from ./input.dmg -format UDTO ./output.iso

# Expected: UDTO (DVD/CD master) image written to output.iso.cdr.
# Note: .cdr extension handling may differ from hdiutil, so
# confirm output filename before scripting rename step.

Each of these is a mechanical change, but the risk lies in the details. The create command’s split into blank and from means a simple find-and-replace of hdiutil with diskutil image will produce invalid commands for about half of all real-world create uses. That is why the command mapping table, not a simple text replacement, should guide the migration.

Limitations and Trade-offs Practitioners Hit

The deprecation is not a straightforward drop-in replacement, and the friction points should be identified before they cause build failures.

The output format is not guaranteed to match. The hdiutil man page explicitly states that attach output has been stable since Mac OS X 10.0 and is intended to be program-readable, with a specific structure of /dev node, tab, content hint, tab, and mount point. The replacement does not provide that same documented stability guarantee in the available documentation. Any parser that relied on the exact byte layout of hdiutil output needs to be tested against diskutil image.

The create command split is a common source of errors. Because create, create -srcfolder, create -srcdevice, and convert all map to different diskutil image subcommands, a blanket replacement silently changes behavior. A script that created a blank image will, after a simple swap, try create from and fail, or vice versa.

Unmaintained wrappers will not update automatically. The go-darwin/hdiutil wrapper is a clear example: seven years without updates means no one is maintaining the migration for its users. Teams relying on abandoned wrapper libraries face a fork-or-rewrite decision, not a simple dependency update.

ASIF is a strict limitation, not a warning. The most significant limitation is that hdiutil cannot handle ASIF images at all. Any workflow that encounters an ASIF file, including tooling Apple may adopt as default, will fail until it switches to diskutil image.

You can still use hdiutil for commands that continue to work. The deprecation notice says removal will happen “in a future macOS release,” not in Golden Gate. That provides some time, but it also means teams that delay migration are building technical debt against a removal date Apple has already announced.

What to Watch Through 2026

The deprecation is an initial step, not a final state. Several indicators will show how quickly to act.

First, watch whether Apple documents a structured output mode for diskutil image that matches the reliability of the old hdiutil -plist and -puppetstrings flags. If that output format stabilizes, the migration becomes straightforward. If it remains inconsistent, teams should isolate all disk-image calls behind a single internal function so the switch happens in one place.

Second, watch whether ASIF becomes the default sparse format in any Apple tool. Once a widely used Apple utility starts producing ASIF files, the practical deadline for hdiutil moves from “future release” to “immediate.”

Third, watch the wrapper ecosystem. Projects like go-darwin/hdiutil are an early indicator: if the community starts forking and updating these libraries, that shows migration is happening broadly. If they remain inactive, the responsibility shifts to individual teams.

The practical approach in 2026 is to treat this as a planned, low-risk migration rather than an emergency. Audit every script, CI step, and library call that uses hdiutil. Map each one to its diskutil image equivalent using the command table. Wrap calls behind a single abstraction now, so when Apple removes hdiutil entirely, the change is a one-line update instead of a scramble.

More in-depth coverage from this blog on closely related topics:

Sources and References

Sources cited while researching and writing this article: