hdiutil Is Deprecated in macOS 27. Its Replacement Already Shipped.

macOSTahoe ·
hdiutil Is Deprecated in macOS 27. Its Replacement Already Shipped.

Apple deprecated hdiutil in macOS 27 in favor of diskutil image. That command is already on your Mac today — and it is missing things you probably use.

The man page in macOS 27 Golden Gate carries a line that has never been there before:

In macOS 27.0, hdiutil is deprecated. Use diskutil image instead for all disk image operations.

hdiutil has been the way you make, mount, convert, and inspect disk images on the Mac since Mac OS X 10.0. If you have ever shipped a .dmg, scripted an installer, built a CI job that packages a Mac app, or made an encrypted container to keep something private, you have used it — directly or through something that called it for you.

Here is the part that most of the coverage missed: the replacement is not coming. It is already on your Mac. Open Terminal on macOS 26 Tahoe right now and run diskutil image. It answers.

Key Takeaways

  • diskutil image already works on macOS 26. Verified on macOS 26.5.2 (build 25F84). You can migrate and test scripts today, before macOS 27 ships.
  • Deprecated is not removed. hdiutil still works in macOS 27. Nothing breaks on day one. But Apple has been trimming it for seven years, and the man page documents every step.
  • The command surface is far smaller. hdiutil exposes 23 verbs. diskutil image exposes 5 subcommands.
  • There is no detach. You can attach a disk image with diskutil image but not detach it — that moves to diskutil eject.
  • Some things genuinely have no replacement yet, including verify, compact, and makehybrid. If your build scripts use those, you do not have a migration path today.

First: Confirm It On Your Own Mac

Do not take my word for any of this. One command:

diskutil image

On macOS 26.5.2 that prints:

OVERVIEW: Manipulate disk images (attach, create, etc)

USAGE: diskutil image [--verbose] [--stdinpassphrase] [--plist] <subcommand>

SUBCOMMANDS:
  attach                  Attach a disk image as a device.
  info                    Print info regarding a disk image.
  create                  Create a disk image. Either blank or from an existing
                          source (disk, disk image or folder).
  resize                  Resize a given image to a specified size if
                          applicable.
  chpass                  Change the passphrase of a given encrypted image.

Five subcommands. Now compare that to what hdiutil offers, straight from its own man page:

Common verbs include attach, detach, verify, create, convert, and compact.

The rest of the verbs are currently: help, info, burn, checksum, chpass,
erasekeys, imageinfo, isencrypted, mountvol, unmount, plugins, udifrez,
udifderez, resize, segment, makehybrid, and pmap.

That is 23 verbs against 5 subcommands. That ratio is alarming at first glance and it is also misleading, because a straight verb-by-verb comparison gets the answer wrong. Several hdiutil verbs are folded into diskutil image under different names, several were already deprecated years ago, and one important one moved to a different command entirely.

Working out which is which is the actual migration, so let us do it properly.

This Did Not Come Out of Nowhere

Before the migration table, some context that makes the deprecation look less abrupt. hdiutil's man page contains a compatibility section that reads as a seven-year record of Apple narrowing the tool. This is on your Mac now — man hdiutil and search for the version headings:

macOS 10.15

  • Introduced lzma compression in the ULMO format
  • Deprecated OS 9-style dual-fork file support (hdiutil flatten/unflatten)
  • Removed the deprecated hdiutil internet-enable command and the IDME attach flags

macOS 11.0

  • Removed support for DiskCopy42, DART and NDIF formats
  • Removed support for AppleSingle and MacBinary encodings
  • Removed OS 9-style dual-fork file support
  • Changed the default file system for new images to APFS

macOS 12.0

  • Deprecated the UDBZ format (bzip2 compression)
  • Deprecated segmented UDIF images (hdiutil segment, -segmentSize)
  • Deprecated hdiutil udifrez/udifderez (embed and extract resources)

macOS 13.0

  • Removed the encrypted-encoding-version option; all new encrypted images use version 2

The man page also flags, inline, that -passphrase is insecure, that segmented images are deprecated, and that UDBZ is deprecated.

Read as one arc, macOS 27's deprecation is the last step of a process that started around 2019, not a decision made this summer. That matters for planning: Apple removes things from this tool slowly and announces them in the man page first. hdiutil in macOS 27 is deprecated, not gone, and there is no announced removal date.

The Migration Table

This is the map. I tested each of these on macOS 26.5.2.

What you wanthdiutildiskutil image
Mount an imagehdiutil attach x.dmgdiskutil image attach x.dmg
Unmount an imagehdiutil detach /dev/diskNNot in diskutil image — use diskutil eject /dev/diskN
Make a blank imagehdiutil create -size 1g -fs APFS x.dmgdiskutil image create blank --size 1g x.dmg
Make an image from a folderhdiutil create -srcfolder ./dir x.dmgdiskutil image create from ./dir x.dmg
Convert formathdiutil convert in.dmg -format UDZO -o out.dmgdiskutil image create from in.dmg out.dmg --format UDZO
Inspect an imagehdiutil imageinfo x.dmgdiskutil image info x.dmg
Check if encryptedhdiutil isencrypted x.dmgdiskutil image info → Is Encrypted:
Resizehdiutil resize -size 2g x.dmgdiskutil image resize
Change passphrasehdiutil chpass x.dmgdiskutil image chpass x.dmg
Verify checksumhdiutil verify x.dmgNo equivalent
Compact a sparse imagehdiutil compact x.sparsebundleNo equivalent
Make a hybrid/ISO imagehdiutil makehybridNo equivalent
Embed a license agreementhdiutil udifrezNo equivalent (deprecated in macOS 12)
Burn to optical mediahdiutil burnNo equivalent

The convert surprise

The most common mistake I have seen in the early commentary is "there is no convert." There is — it is just not called that.

OVERVIEW: Create a disk image from an existing source (disk, disk image or
folder).

Source and destination disk image can be the same, which will perform the
conversion in place.

diskutil image create from takes a disk image as its source, so it is hdiutil convert under a different name, and it additionally supports in-place conversion, which hdiutil convert never did. If you count verbs rather than reading the help text, you will conclude a capability was dropped when it was actually extended.

The detach gap is real

This one is not a rename. There is no detach anywhere in diskutil image:

$ diskutil image detach /dev/disk12
Error: 2 unexpected arguments: 'detach', '/dev/disk12'
Usage: diskutil image [--verbose] [--stdinpassphrase] [--plist] <subcommand>

The replacement is the top-level diskutil command:

$ diskutil eject /dev/disk12
Disk /dev/disk12 ejected

Which works fine — but note what it does to a script. The clean symmetry of hdiutil attach / hdiutil detach becomes diskutil image attach / diskutil eject, two different subcommand levels of the same binary. Any wrapper function you have that pairs attach and detach needs restructuring, not a find-and-replace.

Migrating disk image scripts

What diskutil image Does Better

It would be unfair to present this as pure loss. Three things are genuinely improved.

ASIF, which hdiutil cannot make at all

diskutil image supports the Apple Sparse Image Format. hdiutil does not. If you want ASIF — and for virtual machine disks on APFS it is the format Apple has been steering toward — diskutil image is the only tool that produces it.

The format lists are worth knowing:

create blank --format : RAW, ASIF, UDSB          (default RAW)
create from  --format : ASIF, RAW, UDRO, UDSB,
                        UDZO, ULFO, ULMO         (default ULFO)

It attaches over HTTP and makes RAM disks directly

From the attach help:

Supports 'ram://<size>', file paths, http[s].

Making a RAM disk on macOS has traditionally been the awkward two-step hdiutil attach -nomount ram://<sectors> followed by newfs_hfs or diskutil eraseVolume. Here it is one argument to a documented flag.

It is substantially faster

Jeff Johnson of Lapcat Software benchmarked the two while investigating the deprecation in early August 2026 and measured diskutil image completing a create operation in 40–45 seconds against hdiutil's 110–115 seconds, producing a smaller image in the process. That is not a rounding difference. For a CI job that builds disk images on every commit, it is meaningful.

What Will Actually Break In Your Scripts

Deprecation warnings do not break builds. These things will.

1. -puppetstrings has no replacement

hdiutil's -puppetstrings flag emits machine-parseable progress output, which is precisely what a build system wants. Johnson flags its absence as one of the notable gaps. diskutil image has --plist for structured results, and it prints human-readable progress like:

[5% completed] [79% completed] [98% completed] [100% completed]
test.dmg created

If you have tooling that parses PERCENT: lines from hdiutil, that parser has nothing to attach to.

2. Several create options are simply gone

Johnson's writeup lists -[no]crossdev, -[no]scrub, -[no]anyowners, -skipunreadable, -[no]atomic, and -copyuid as having no counterpart. If you build images from folders in a controlled way — installers, forensic captures, anything where ownership or which files get included must be exact — read that list carefully. -skipunreadable and -copyuid in particular are load-bearing for some packaging scripts.

3. Scrubbing behavior changed silently

Johnson reports that diskutil image excludes temporary files such as trash folders automatically, behaving as though -scrub is always on. hdiutil scrubbed only when asked. If your image contents are expected to be byte-identical to a source directory, this will produce a different image without telling you.

4. Permission handling fails quietly

This is the one I would test first. Johnson found that where hdiutil triggers an authentication prompt when it hits root-owned files, diskutil image does not prompt and simply fails. A script that used to pause for credentials will now produce an incomplete image and, depending on your error handling, may report success.

If you build images from directories that contain files you do not own, verify the output rather than trusting the exit code.

5. Logging is thinner

Verbose output from diskutil image is less detailed than hdiutil's. When a build fails at 3 a.m., that is when you find out.

How To Migrate Without Breaking macOS 26 Support

Most of us have to support both for a while. The good news, and the practical point of this whole article, is that you do not have to branch on OS version, because diskutil image exists on macOS 26 as well.

Detect the capability, not the version:

#!/bin/bash
# Prefer diskutil image; fall back to hdiutil where unavailable.

if diskutil image --help >/dev/null 2>&1; then
  USE_DISKUTIL=1
else
  USE_DISKUTIL=0
fi

make_image_from_folder() {
  local src="$1" dst="$2"
  if [ "$USE_DISKUTIL" -eq 1 ]; then
    diskutil image create from "$src" "$dst" --format UDZO
  else
    hdiutil create -srcfolder "$src" -format UDZO "$dst"
  fi
}

attach_image() {
  local img="$1"
  if [ "$USE_DISKUTIL" -eq 1 ]; then
    diskutil image attach "$img" --nobrowse
  else
    hdiutil attach "$img" -nobrowse
  fi
}

detach_device() {
  # Note the asymmetry: detach is NOT under `diskutil image`.
  local dev="$1"
  if [ "$USE_DISKUTIL" -eq 1 ]; then
    diskutil eject "$dev"
  else
    hdiutil detach "$dev"
  fi
}

Then verify the output, because that is where the silent differences live:

# Compare what actually landed in the image against the source.
diskutil image attach build.dmg --nobrowse --mountPoint /tmp/verify_mnt
diff -rq ./src /tmp/verify_mnt/src
diskutil eject /tmp/verify_mnt

That diff -rq is the step I would not skip. Between the always-on scrubbing and the quiet permission failures, an image that builds successfully is not the same thing as an image that contains what you meant.

If you are building out a Mac development environment from scratch, our Apple silicon development environment setup guide covers the surrounding tooling, and the Terminal mastery guide covers the shell fundamentals these scripts assume.

Verifying disk image contents

A Worked Example, Start To Finish

Here is a complete round trip run on macOS 26.5.2, so you can see the real output rather than a reconstruction.

Create an image from a folder:

$ mkdir -p src && echo "hello" > src/file.txt
$ diskutil image create from src --format UDZO test.dmg
[5% completed] [79% completed] [98% completed] [99% completed] [100% completed]
test.dmg created

Inspect it:

$ diskutil image info test.dmg
Image Format: UDZO
Format Description: UDIF read-only compressed image (zlib)

	Identity Info:
		UUID: 061189CB-7502-4EA6-BFE3-424442C16D10

	Size Info:
		Empty Bytes: 3437056
		Total Bytes: 4233216

	Compression Info:
		Compressed Bytes: 4124
		Compression Type: zlib

	Encryption Info:
		Is Encrypted: 0

	Master Checksum Info:
		Checksum Type: crc32
		Checksum Value: c4 e3 90 4b

Note that info covers what hdiutil imageinfo, isencrypted, and part of checksum used to give you separately. It reports the stored checksum — it does not verify it. That is the hdiutil verify gap.

Attach it:

$ diskutil image attach test.dmg
/dev/disk12  	GUID_partition_scheme
/dev/disk13s1	Apple_APFS_Volume    	/Volumes/src

Detach it — with the different command:

$ diskutil eject /dev/disk12
Disk /dev/disk12 ejected

Encrypted Images

If you use disk images as encrypted containers, the mechanics are straightforward but the options are narrower.

# Create an encrypted blank image
diskutil image create blank --encrypt --size 10g --volumeName Vault vault.dmg

# Provide the passphrase on stdin rather than interactively
printf '%s' "$PASSPHRASE" | diskutil image create blank --encrypt --stdinpassphrase \
  --size 10g --volumeName Vault vault.dmg

# Change the passphrase later
diskutil image chpass vault.dmg

--encrypt is documented as AES-256 and there is no algorithm choice, which is a simplification rather than a loss — Apple removed the older encrypted encoding version back in macOS 13.

The --stdinpassphrase flag is the one to use in any script. hdiutil's own man page warns that -passphrase is insecure, for the ordinary reason that a passphrase on a command line is visible in the process table to every user on the machine.

If you are relying on disk images for privacy rather than convenience, it is worth reading our Mac security and privacy guide for where an encrypted image sits relative to FileVault — they solve different problems, and an encrypted .dmg protects nothing while it is mounted.

What Disk Images Are Still For

It is worth asking why any of this matters, because "disk image" sounds like a relic and the tooling around it is quietly load-bearing in several places.

Application distribution. The .dmg remains the standard way to ship a Mac app outside the App Store. A compressed, read-only image containing an app bundle and a symlink to /Applications is the drag-to-install convention users know. Every one of those is built by a script that calls a disk image tool.

Encrypted containers. An encrypted .dmg is a portable, self-contained vault that mounts as a volume and works on any Mac without special software. Unlike FileVault, which protects a whole disk at rest, an encrypted image protects a specific set of files that you can move around — onto a USB stick, into cloud storage, to a colleague.

Virtual machine disks. This is where ASIF matters and where Apple's direction becomes obvious.

Sparsebundles for network backup. Time Machine backing up to a network destination stores the backup inside a sparsebundle — a disk image split into many small band files so that only changed bands need syncing. Anyone who has maintained one of these has run hdiutil compact to reclaim space from deleted bands.

Forensics and archival. A block-level image of a volume, with a checksum, is how you preserve a disk's exact state. hdiutil verify is how you confirm it later.

Look at that list against the migration table and the gaps line up with specific communities rather than being random. App developers lose the license-agreement mechanism and -puppetstrings. Backup and sparsebundle users lose compact. Archival and forensics users lose verify. Everyone doing routine create-convert-attach work is fine.

ASIF: The Format Only the New Tool Makes

The Apple Sparse Image Format is the clearest signal of why Apple wants people off hdiutil, because hdiutil cannot produce it at all.

A sparse image only occupies disk space for blocks that actually contain data. A 100GB sparse image holding 10GB of files takes about 10GB on disk and grows as you add data. The old UDSP sparse image and UDSB sparsebundle formats did this too, with known problems: sparsebundles fragment into thousands of band files, and both formats historically reclaimed space poorly, which is exactly why hdiutil compact had to exist.

ASIF is designed against APFS rather than bolted on top of it, which lets the filesystem's own sparse-file support do the work instead of the image format emulating it. In practice the payoff shows up most in virtualization, where a VM's virtual disk is a large mostly-empty file that changes constantly — the case that punished the old formats hardest.

You can create one today:

# A 100GB ASIF image that occupies only what it uses
diskutil image create blank --format ASIF --size 100g \
  --volumeName VMDisk vmdisk.asif

# Convert an existing image to ASIF
diskutil image create from old.dmg new.asif --format ASIF

Note that the format is inferred from the extension — create blank defaults to RAW "unless the image path has .asif or .sparsebundle extension." Naming the file correctly is enough; passing --format as well is belt and braces.

The trade-off is portability. ASIF is new, and an ASIF image will not open on an older macOS or on anything that is not a Mac. For a VM disk or a local working volume that is irrelevant. For anything you hand to another person, use UDZO and keep the compatibility.

Where This Fits in a Distribution Pipeline

If you ship a Mac app outside the App Store, the disk image step sits in the middle of a chain, and it is worth seeing where the change lands.

#!/bin/bash
set -euo pipefail

APP="build/MyApp.app"
DMG="dist/MyApp.dmg"
STAGE="$(mktemp -d)"

# 1. Sign the app bundle (unchanged by any of this)
codesign --force --options runtime --timestamp \
  --sign "Developer ID Application: Example Inc (TEAMID123)" \
  "$APP"

# 2. Stage the contents the user will see
cp -R "$APP" "$STAGE/"
ln -s /Applications "$STAGE/Applications"

# 3. Build the image — the step this article is about
diskutil image create from "$STAGE" "$DMG" --format UDZO

# 4. Sign the image itself
codesign --force --timestamp \
  --sign "Developer ID Application: Example Inc (TEAMID123)" \
  "$DMG"

# 5. Notarize and staple
xcrun notarytool submit "$DMG" --keychain-profile "AC_NOTARY" --wait
xcrun stapler staple "$DMG"

rm -rf "$STAGE"

Only step 3 changes. Signing, notarization, and stapling are unaffected — they operate on the finished image and do not care which tool produced it.

Two things to watch in a real pipeline. First, verify the staged contents landed correctly, because of the silent scrubbing and permission behavior described above — a diff -rq between $STAGE and the mounted result is cheap insurance. Second, if your current script embeds a license agreement with hdiutil udifrez, that step has no replacement and has been deprecated since macOS 12. Keep hdiutil for it while it exists and plan an alternative.

Troubleshooting Common Issues

"diskutil image: command not found" or the subcommand is unrecognized

Problem: You are on a macOS version older than 26, where the image verb does not exist.

Solution: Use the capability check shown above rather than assuming. diskutil image --help >/dev/null 2>&1 returns non-zero on systems that lack it, which is a reliable branch. Do not test sw_vers — the presence of the subcommand is what you actually care about.

The image builds but is missing files

Problem: Two likely causes. Either diskutil image skipped files it could not read as your user and did not prompt for authentication, or its always-on scrubbing removed items hdiutil would have included.

Solution: Mount the result and diff -rq it against the source directory. If files are missing because of ownership, run the build with the necessary privileges rather than expecting a prompt. Do not rely on the exit code alone.

Progress parsing broke in CI

Problem: -puppetstrings has no diskutil image equivalent, so scripts that parsed hdiutil's machine-readable progress have nothing to read.

Solution: Use --plist for the structured result and treat progress as unavailable. If your CI needs progress specifically, keeping hdiutil for that step is legitimate — it is deprecated, not removed, and there is no announced removal date.

Cannot detach — "resource busy"

Problem: Something still has the volume open. This behaves the same as it always did.

Solution: lsof +D /Volumes/YourVolume to find the holder, then diskutil eject. Spotlight indexing and antivirus scanners are frequent culprits; mounting with --nobrowse avoids some of it by keeping the volume out of Finder.

A .dmg with a license agreement no longer builds

Problem: The license-agreement mechanism relies on hdiutil udifrez, which Apple deprecated back in macOS 12 and which has no diskutil image counterpart.

Solution: There is no replacement path. Keep using hdiutil for that step while it exists, and plan for a distribution method that does not depend on an embedded agreement. This has been on notice for four years, which is worth knowing if you are only discovering it now.

FAQ

Does hdiutil still work in macOS 27?

Yes. It is deprecated, not removed. Deprecation is Apple signalling intent and starting a clock — it is not a functional change. Nothing that works today stops working when you install macOS 27.

When will hdiutil actually be removed?

Apple has not said. Looking at the man page's own history, Apple's pattern with this tool has been to deprecate a feature in one release and remove it one or more major versions later — internet-enable and the OS 9 dual-fork support each took at least a full cycle. Anyone giving you a specific removal version is guessing.

Can I use diskutil image on macOS 26 Tahoe?

Yes, and this is the most useful fact in this article. Verified on macOS 26.5.2 (build 25F84). You can migrate scripts and test them now, on the OS you already run, rather than waiting for macOS 27.

Is diskutil image a full replacement for hdiutil?

No, not today. verify, compact, makehybrid, and burn have no counterpart, and several create options for controlling exactly which files get included are absent. For the common path — create, convert, attach, inspect, resize, encrypt — it is complete.

Why did Apple do this?

Apple has not published a rationale. What is observable is that diskutil image is faster in benchmarks, produces smaller images, supports the newer ASIF format that hdiutil cannot produce, and presents a much smaller command surface. Consolidating disk-image handling into diskutil alongside the rest of storage management is a coherent direction. That is a reading of the evidence, not a statement from Apple.

Will my app break if it shells out to hdiutil?

Not in macOS 27. Plan to move anyway — and use the capability check so a single code path covers both, which is easier than it sounds precisely because the new command already exists on macOS 26.

Conclusion

The headline — a 25-year-old Terminal command is being retired — is true but misleading in both directions. It undersells the change for anyone whose build scripts use verify, compact, makehybrid, or the fine-grained create options, because those have no path forward today. And it oversells it for everyone else, because hdiutil still works in macOS 27, Apple has announced no removal date, and the deprecation is the last step of a narrowing that has been documented in the tool's own man page since macOS 10.15.

The genuinely useful thing to know is that the replacement is not in the future. diskutil image is on your Mac right now, on macOS 26, with create, attach, info, resize, and chpass working. You can do this migration on a Tuesday afternoon on the OS you already have, verify it with diff -rq, and stop thinking about it.

Just remember that detach is not where you expect it.

Related reading: Terminal mastery on macOS, Apple silicon development environment setup, and encrypted HFS+ volumes are being dropped in macOS 28.