What to do when a disk image won’t mount

Disk images are normally both robust and reliable, but every once in a while they can cause problems.

Let’s say you wanted some files which are stored in an old disk image, so you double-click the image to mount it, and see an error message. Worse still, the image hasn’t been mounted, and repeating the action doesn’t help.


To know how to resolve this, you need to understand what happens when your Mac tries to mount that disk image.

A disk image is just a file that macOS opens and mounts as if the data contained within it were stored on a disk volume. Before it will offer you the contents of that virtual volume, macOS puts it through some basic checks.


If the disk image is read-only (as are most installers and apps supplied on disk images) or compressed, when it’s saved it includes a checksum of its entire contents. When you open and mount it, macOS checks that checksum. Note that this doesn’t apply to read/write disk images, as they don’t store checksums.

Calculating the checksum takes a while, so before doing that, macOS looks to see if it has already been done. If it finds an extended attribute of type com.apple.diskimages.recentcksum which contains a more recent checksum than the timestamp on the disk image, it accepts that rather than calculating it afresh. This explains why mounting a disk image for the first time usually displays a progress dialog while the checksum is checked, but the next time the image normally mounts more quickly.

If there’s no current checksum stored in an extended attribute, macOS calculates a new one, compares it against the checksum given in the disk image, and – if they tally – saves the checksum in an extended attribute of type com.apple.diskimages.recentcksum.

The error message shown above is typically seen when the checksums do not tally. This normally means that the disk image has been damaged, and you should obtain a fresh one. If that is an option, then it is the best one.

If you cannot obtain another copy, and have to get the best out of the disk image that you have, you can force it to be mounted regardless of the checksum issue. Before going any further, save all open documents and batten down your Mac’s hatches in case mounting the damaged disk image causes a kernel panic, which it could. When you’re ready to proceed, open Terminal and type in a command like
hdiutil attach filename.dmg -noverify or
hdiutil attach filename.dmg -ignorebadchecksums
where filename.dmg is the full name of the disk image file. They should have identical effect.

You should then see a listing of each of the partitions mounted by macOS, such as
/dev/disk4 Apple_partition_scheme
/dev/disk4s1 Apple_partition_map
/dev/disk4s2 Apple_HFS /Volumes/Packages 1.2.2

If you’re unsure whether the cause of your problems is a checksum error, look at the disk image using xattred, my free extended attribute editor. If the disk image has passed the checksum check, there will be an extended attribute of type com.apple.diskimages.recentcksum recording that event. If it failed, then that xattr won’t be present, but there will be one with a type name starting com.apple.metadata:kMDLabel_ to record the checksum failure.


Disk check by fsck

The other common error with disk images is that, although their checksums match, the file system within the virtual volume is damaged, and cannot be mounted.

File systems are not routinely checked in all disk images, only those which have a quarantine flag attached and have not already passed an fsck check are put through the process. macOS should select the right form of fsck (specific to the file system contained in the disk image) and use that. When it does, it then adds an extended attribute of type com.apple.diskimages.fsck to the disk image file, and shouldn’t need to repeat it when you next mount that disk image.

You can force macOS to bypass the fsck step using a command in Terminal of the form
hdiutil attach filename.dmg -noautofsck
where filename.dmg is the name of the disk image file. Again, this could result in a kernel panic when the disk image is mounted, so batten down your Mac’s hatches before trying this.

Signature check (High Sierra)

macOS 10.13 High Sierra may also add a signature check after those steps, to verify whether the disk image has been signed, and any app installed from it can bypass app translocation. Any failure at this step might still allow you to install an app, but for it to undergo app translocation. If not, and macOS barfs at any attempt to use the disk image, there is nothing that you can do with that disk image; you will need to obtain a new one with a correct signature (or none at all).

Removing extended attributes

A common suggestion which appears repeatedly is to remove extended attributes from the disk image. Although this might have worked in the past, it will not solve the problem in recent versions of macOS. However, if you want to try it, you can do this using xattred (from Downloads above) or in Terminal with a command like
xattr -d com.apple.diskimages.fsck filename
xattr -d com.apple.diskimages.recentcksum filename
where filename is the full file name of the disk image. These remove the fsck xattr and the checksum xattr respectively. You might also try removing any com.apple.metadata:kMDLabel_ xattr, and the quarantine xattr com.apple.quarantine if you wish. But I don’t think that any of those would help, for the reasons explained above.

Be suspicious

Finally, as you’re trying these, ask yourself whether this disk image might be malicious rather than just faulty. If you received this disk image as an attachment to a message which came from someone you don’t know well, or downloaded it from a website, consider whether it might be malware. At least in the first instance, you might be best treating it as hostile until proven innocent.