everyday mac tools

What a sparsebundle file is on a Mac, and how to open or shrink one

· 6 min read

A sparsebundle file on a Mac is a disk image: a container that behaves like a drive when you open it. Double-click it and its contents appear as a volume in Finder’s sidebar; eject the volume when you are done. It differs from an ordinary .dmg in two ways. It grows as you add files instead of taking its full size up front, and it is stored as many small pieces instead of one large file. Sparsebundles are often encrypted, in which case macOS asks for a password before it opens.

How a sparsebundle is built

In Finder a sparsebundle looks like a single file. It is really a package, which is a folder that Finder presents as one item. Right-click it and choose Show Package Contents and you will see an Info.plist, a token file, and a folder named bands filled with files that have short hexadecimal names. Each band holds up to 8 MB of the image by default.

Do not rename, move or delete anything in there. One missing band can stop the whole image from mounting.

The bands are the reason the format exists. When a file inside the image changes, only the bands that hold it change, so a backup or a sync has to copy a few megabytes instead of the whole image. That is why Time Machine uses a sparsebundle when it backs up to a network drive.

There are two close relatives. A .sparseimage also grows as you fill it but is one single file. A .dmg has a fixed size, and is what most Mac software is delivered in.

Open one

  1. Double-click the sparsebundle.
  2. If it is encrypted, type the password. Leave “Remember password in my keychain” unticked if the point is to keep the contents private from anyone using your login.
  3. The volume appears in the Finder sidebar under Locations.
  4. Open, edit and save files on it as you would on any drive.
  5. Eject it when you are finished, using the eject symbol beside its name in the sidebar.

Step 5 is the one people skip. While the volume is mounted, its contents are readable by anything running under your account, encrypted or not. The protection applies only once it is ejected.

The Terminal equivalents are hdiutil attach followed by the path to the sparsebundle, and hdiutil detach followed by the volume’s path, such as /Volumes/Private.

Make one

  1. Open Disk Utility and choose File, New Image, Blank Image.
  2. Give it a file name, and a volume name in the Name field.
  3. Set Size to the largest it should ever grow to.
  4. Set Format to APFS.
  5. Set Encryption to 256-bit AES encryption if you want a password on it, and enter the password twice.
  6. Set Image Format to sparse bundle disk image.
  7. Click Save.

The same thing in Terminal:

hdiutil create -size 10g -type SPARSEBUNDLE -fs APFS -encryption AES-256 -volname Private ~/Documents/Private.sparsebundle

The size is a ceiling, not a reservation. A new sparsebundle takes very little room until you put files in it. Encrypt a folder on a Mac with Disk Utility, step by step goes through the encrypted version in more detail.

Why it never gets smaller, and how to shrink it

A sparsebundle grows by itself but does not shrink by itself. Delete files inside it and the space becomes free inside the image, while the bands already written stay on your disk. To hand that space back to the Mac:

  1. With the volume mounted, empty the Trash. Files deleted from the image wait in a hidden Trash on that volume until you do.
  2. Eject the volume.
  3. In Terminal, run:
hdiutil compact ~/Documents/Private.sparsebundle
  1. Enter the password if the image is encrypted.

On a laptop running on battery, hdiutil declines to compact. Plug in the charger, or add -batteryallowed to the command.

The command reports how much it reclaimed, and the amount varies. If it returns very little and you need the space, the dependable route is to create a new sparsebundle, copy the contents across, check the copy opens, and delete the old one.

To raise the ceiling instead, eject the volume and run hdiutil resize -size 20g followed by the path. To see how much room the bundle really takes, select it in Finder and choose File, Get Info, or run du -sh followed by the path.

When a sparsebundle will not open

“No mountable file systems.” The usual cause is an incomplete copy. Compare the size of your copy with the original using du -sh on both, and copy it again with the volume ejected. Copying a sparsebundle while it is mounted is a common way to end up with a broken one.

It lives in a synced folder. Sync services see a sparsebundle as a folder containing thousands of files. If only some bands have arrived on the second Mac, it will not mount. Wait for the sync to finish, and never have the same image mounted on two Macs at once.

It came from a drive used with another operating system. Other systems show the package as a plain folder. If anyone tidied, renamed or sorted the files inside while it was there, the image is damaged.

The password is refused. There is no bypass for an encrypted image. Forgot the password to an encrypted disk image? covers the few things worth trying, starting with your keychain.

It mounts but files are damaged. Open Disk Utility, select the mounted volume in the sidebar and run First Aid.

Sparsebundles are a Mac format. If the files need to reach someone on Windows, copy them out and send them another way.

Locked folders that are sparsebundles underneath

An encrypted sparsebundle is a sound way to keep a folder private. Its weak point is the routine: mount, work, remember to eject. Forget the last step and the contents sit open for the rest of the day.

Hushbox uses the same format and removes the routine. Right-click a file or folder in Finder, choose Lock with Hushbox, and it becomes a locked item in the same place. Double-click to unlock with Touch ID or the Hushbox password. It locks again by itself when the screen locks, when the Mac sleeps, or after the idle time you pick.

What it creates is an AES-256 encrypted disk image of the kind Disk Utility makes, built with Apple’s own tools. If Hushbox ever goes away, rename the locked item so it ends in .sparsebundle, double-click it, enter the password, and macOS opens it without Hushbox. Each locked item uses about 33 MB of extra space, so for many small files, put them in one folder and lock the folder. It is $9 once for 2 Macs, free for 24 hours with every feature, and unlocking stays free after the trial. There is no password recovery, so keep the password in a password manager. How to password protect a folder on a Mac compares it with the built-in routes.

Questions

I found a sparsebundle on a network drive named after my Mac. Can I delete it? That is almost certainly the Mac’s Time Machine backup. Deleting it deletes every backup inside. Only remove it if you have another backup or no longer own that Mac.

Is an encrypted sparsebundle more secure than an encrypted .dmg? No. Both can use the same AES-256 encryption. The difference is how they are stored and whether they can grow.

Does Time Machine back up a sparsebundle sensibly? Yes. Only the bands that changed are copied, and they are copied in their encrypted form, so the contents stay protected in the backup. Private files and Time Machine explains what else your backups keep.