macOS diskutil: APFS Volume Groups and the -sibling Flag

In December 2025 a reader named Maik Kaune left a question on this post that turned out to be sharper than the article it was attached to. He had already worked out how to build a System/Data pair — create an empty Data volume, then use addVolume with -groupWith to create the group and the System volume in one go. Then he hit the wall: “the manual and command description shows an option called ‘-sibling’! But no information about the meaning and usage?”

He was right, and the reason is worth spelling out. -sibling is not a missing feature or a hidden capability. It is a documentation gap — the option is named in the syntax and then never mentioned again.

The -sibling option the man page names but never explains

The addVolume synopsis in the macOS 26 Tahoe man page reads:

addVolume  containerReferenceDevice filesystem name
           [-passprompt] | [-passphrase passphrase] |
           [-stdinpassphrase] [-passphraseHint passphraseHint]
           [-reserve reserve] [-quota quota] [-role roles]
           [-group[With] | -sibling groupDevice] [-nomount]
           [-mountpoint mountpoint]

The line that answers the question is [-group[With] | -sibling groupDevice]. The pipe character marks an OR: the two spellings are alternatives to each other, and both take the same groupDevice argument. -sibling is a synonym for -groupWith. They do the same thing — name the volume you want the new volume grouped with.

The bracketed [With] adds a third spelling, since it makes the suffix optional. So -group, -groupWith and -sibling are three ways to write one option. A plausible reading — and this is inference from the syntax rather than anything Apple states — is that “sibling” was the internal term in the code and “groupWith” became the documented spelling, with the older name kept accepted for compatibility.

Why searching the man page for “sibling” doesn’t help

This is the part that makes the reader’s “not explained anywhere” literally true rather than just frustrated. Run the word through the whole man page and there are exactly three hits, none of which define the option.

Two are synopsis lines — the addVolume one above, and the same fragment on eraseVolume. The third is prose, but it is a different word entirely, in a passage about quotas: a volume can fill its container “at the expense of sibling Volumes.” That is ordinary English for neighbouring volumes. It has nothing to do with the flag, and it is the only place the word appears in running text.

Meanwhile the prose that describes what the option does names only -groupWith:

If you specify -groupWith, your new APFS Volume will become a
member of the same APFS Volume Group as the APFS Volume
groupDevice.  If groupDevice is not yet associated with any
group, such will be created automatically when appropriate.

So a reader who greps for sibling finds the option offered but never described, and a reader who reads the description never learns that sibling is the same thing. The two halves of the answer are in the same man page and never touch.

The eraseVolume entry repeats the pattern. Its synopsis carries [-group[With] | -sibling groupDevice], and its prose says only that “the -role and -groupWith options function in the same manner as diskutil apfs addVolume.” Both spellings are accepted; one is documented.

What -groupWith actually does

Two things follow from that description, and the second one surprises people.

First, the group is created on demand. There is no separate “create a group” verb, and you never pass a group ID — you point at an existing volume and the group forms around the pair. Second, and this is why no such verb exists, the man page is explicit that “there is no such thing as an ’empty’ (zero-member) APFS Volume Group.” A group only exists as a relationship between volumes, so it cannot be brought into being before it has members.

That explains why the sequence Maik found is the sequence that works — the Data volume first, then the System volume pointing back at it:

# Create the Data-role volume first
sudo diskutil apfs addVolume disk3 APFS "MyData" -role D

# Then add the System-role volume, grouped with it
sudo diskutil apfs addVolume disk3 APFS "MySystem" -role S -groupWith disk3s5

# Identical in effect — same option, older spelling
sudo diskutil apfs addVolume disk3 APFS "MySystem" -role S -sibling disk3s5

Substitute your own container reference (disk3 here) and the device identifier of the volume you are grouping with. Get those from diskutil apfs list rather than guessing — container numbering is synthesized and shifts between machines and reboots.

Grouping two volumes that already contain data

Maik’s second question was the harder one: if you can create a group with a new System volume, how do you create one from an existing system volume, or from two volumes that already contain data?

The short answer is that you can’t, in any supported way. diskutil has no verb that merges two populated volumes into a group. That looks arbitrary until you look at what a Volume Group actually is, at which point it stops looking like a missing feature.

A Volume Group is not a label

The man page describes the purpose in one dense sentence:

A primary use for APFS Volume Groups is realization of macOS
installations in which "System"-role (for the operating system)
and "Data"-role (for user data) APFS Volumes are functionally
linked (overlaid file namespace, crypto info), yet separated for
reasons of security, backup, and software update.

It also notes that “cryptographic identity, if any, is shared among all members of an APFS Volume Group.” Grouping is not a tag you attach to two volumes — it is a claim that their file namespaces are overlaid and their encryption identity is common.

The phrase carrying the weight there is overlaid file namespace. That is the whole mechanism, compressed into three words and then dropped.

The overlay is firmlinks — a word the man page never uses

That overlay is built from firmlinks: bidirectional mappings that graft directories from the writable Data volume into the read-only, sealed System volume so the two present as one filesystem at /. When you write to /Users/you/Documents, the System volume is not being modified — the path crosses a firmlink onto the Data volume.

Worth noticing: the word firmlink does not appear anywhere in man diskutil. Nor in man apfs.util, man mount_apfs, or man fstab. No amount of reading the manual gets you from “overlaid file namespace” to the thing doing the overlaying — which is a large part of why this question keeps getting asked.

The mapping table is not hidden, though. It is a plain tab-separated file:

$ cat /usr/share/firmlinks
/AppleInternal	AppleInternal
/Applications	Applications
/Library	Library
/System/Library/Caches	System/Library/Caches
/System/Library/Assets	System/Library/Assets
/System/Library/PreinstalledAssets	System/Library/PreinstalledAssets
/System/Library/AssetsV2	System/Library/AssetsV2
/System/Library/PreinstalledAssetsV2	System/Library/PreinstalledAssetsV2
/System/Library/CoreServices/CoreTypes.bundle/Contents/Library	System/Library/CoreServices/CoreTypes.bundle/Contents/Library
/System/Library/Speech	System/Library/Speech
/Users	Users
/Volumes	Volumes
/cores	cores
/opt	opt
/pkg	pkg
/private	private
/usr/local	usr/local
/usr/libexec/cups	usr/libexec/cups
/usr/share/snmp	usr/share/snmp

Nineteen entries on macOS 26 Tahoe. The left column is the path as it appears on the System volume; the right column is the corresponding directory on the Data volume. This file is worth reading once, because it makes the System/Data split concrete in a way the man page’s “overlaid file namespace” does not.

What that rules out

Now the merge question answers itself. Stapling two populated volumes together would mean deciding which volume owns each of those nineteen mappings, reconciling two independent cryptographic identities into the shared one a group requires, sealing a System volume that was never built to be sealed, and generating matching Preboot and Recovery entries. That relationship is established when the group is created or the system is installed. No command-line tool exposes the pieces, and none of it is something a “merge” flag could safely infer from two directory trees full of arbitrary data.

The verbs that exist reflect this. The only way into a group is addVolume -groupWith, which makes a new volume a member. The only group-level verb going the other way is destructive:

deleteVolumeGroup volumeGroupUUID
    Remove all APFS Volumes belonging to the given APFS Volume
    Group from its APFS Container.  All of the Volumes' data
    will be lost.

Create and migrate; don’t merge. If you need an existing system in a group, install macOS to the container and move data in afterwards.

Reading a Volume Group in diskutil apfs

The obvious verb to reach for is diskutil apfs list, and it is the wrong one. It prints every volume in a container as a flat run of siblings; on macOS 26.5.2 the words “Volume Group” do not appear in its output at all. The verb that actually shows grouping is diskutil apfs listVolumeGroups, and its documentation is split in a way that explains why almost nobody finds it: a bare diskutil apfs lists it in the usage text, glossed as “List all current APFS Volume Group relationships,” while man diskutil — 2,370 lines, and the page anyone researching this actually reads — never mentions it once. It works regardless:

$ diskutil apfs listVolumeGroups disk3
+-- Container disk3 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    |
    +-> Volume Group YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
        =================================================
        APFS Volume Disk (Role):   disk3s1 (System)
        Name:                      Macintosh HD
        -------------------------------------------------
        APFS Volume Disk (Role):   disk3s5 (Data)
        Name:                      Macintosh HD - Data

Two members. That is the whole group — System and Data, and nothing else.

This is where a common assumption breaks. Preboot, Recovery and VM live in the same container, and diskutil apfs list prints them in the same flat run as System and Data, which makes it easy to read a Volume Group as a four- or five-volume thing. It isn’t. Membership has a test that doesn’t depend on how the output looks: a volume in a group carries an APFSVolumeGroupID, and a volume outside one doesn’t carry the key at all.

$ diskutil info -plist disk3s1 | plutil -extract APFSVolumeGroupID raw -
YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY

$ diskutil info -plist disk3s5 | plutil -extract APFSVolumeGroupID raw -
YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY

$ diskutil info -plist disk3s2 | plutil -extract APFSVolumeGroupID raw -
<stdin>: Could not extract value, error: No value at that key path or invalid key path: APFSVolumeGroupID

System and Data return the same UUID, and that shared UUID is the group. Preboot (disk3s2) has no such key, and neither does Recovery (disk3s3) or VM (disk3s6) — the same error each time. They are neighbours in a container, not members of a group. Run it against your own device identifiers; the UUID will differ, the shape of the answer won’t.

The UUIDs in the two command outputs above are placeholders; the rest of each output is real. What matters is the relationship they preserve: the System and Data volumes report the same volume group UUID, while Preboot, Recovery and VM report none at all.

One line in diskutil apfs list does deserve the confusion it causes: the System volume reports Not Mounted while the Mac is plainly running. That is expected. What gets mounted at / is a sealed snapshot of the System volume, not the volume itself — the man page covers this in general terms when it notes that where a snapshot is mounted, its “base” volume “will not be mounted.” The Data volume mounts at /System/Volumes/Data, and firmlinks make the two read as one tree.

Knowing the group is exactly two volumes doesn’t make the merge question easier — it moves the obstacle somewhere more specific. Both members answer to one APFSVolumeGroupID, and that UUID is issued when the group comes into existence. No diskutil verb hands one to a volume that already exists, which is exactly why -groupWith only accepts a volume being created. Preboot and Recovery sitting outside the group doesn’t rescue the idea either: a bootable result still needs them, and they are generated by the installer, not by anything a user can reach from the command line.

Which verbs destroy data and which don’t

Volume Group experiments tend to happen on a disk someone cares about, so it is worth being blunt about which side of the line each verb sits on.

Verb	Effect
list, info, apfs list	Read-only, no sudo needed
verifyVolume, verifyDisk	Read-only check
repairVolume	Modifies structures; back up first
addVolume -groupWith	Adds a volume; existing data untouched
eraseVolume	Destroys that volume’s data
deleteVolumeGroup, deleteContainer, partitionDisk	Destroys every volume involved

The asymmetry is the useful thing to remember: adding to a group is cheap and reversible-ish, while anything at group or container level takes the data with it.

Where diskutil goes past Disk Utility

The graphical Disk Utility hides Preboot, Recovery, VM and xART entirely, and offers no way to set a role, a quota, or a reserve. None of the discussion above is expressible in that interface — there is no checkbox for -role S and no view that shows you group membership as membership.

For anything scripted, take the -plist output rather than parsing the human-readable text, which is not a stable interface:

# Structured output for scripts
diskutil info -plist disk3s5
diskutil apfs list -plist

# Read one field without grepping the pretty output
diskutil info -plist disk3s5 | plutil -extract VolumeName raw -

If you are trying to reproduce a System/Data pair by hand, the mental model that saves the most time is this: a Volume Group is not something you assemble out of volumes you already have. It is something that comes into existence with its members, carrying a shared crypto identity and a namespace overlay that nineteen firmlinks make real. -groupWith — or -sibling, same flag — is the only door in, and it only opens for a volume being created right then.