When you format a disk and install macOS on it, making it a startup or boot volume, it has a standard structure, something that has changed greatly over the last couple of years. This article summarises all you need to know about the layout of APFS boot disks and volumes from High Sierra and Mojave through to Big Sur, running on an Intel Mac at least.

Disk layout

A standard APFS boot disk in High Sierra and Mojave consists of an EFI partition and the main APFS container. Within the latter are a minimum of four APFS volumes:

• the startup volume, by default on the internal disk named Macintosh HD, which forms the root of the boot file system,
• Preboot, a small volume of around 40-50 MB,
• Recovery, the Recovery Volume, of around 500 MB,
• VM, containing virtual memory caches, which is upwards of 20 KB depending on use.

Catalina changes that by splitting the startup volume into two:

• the read-only System volume, by default on the internal disk named Macintosh HD, which forms the root of the boot file system,
• the writable Data volume, by default on the internal disk named Macintosh HD – Data, which is normally hidden from view at /System/Volumes and accessed via firmlinks,
• Preboot, a small volume of around 40-50 MB,
• Recovery, the Recovery Volume, of around 500 MB,
• VM, containing virtual memory caches, which is upwards of 20 KB depending on use.

Big Sur goes better than that. The System volume is now the mounted snapshot of a sealed volume known as the Sealed System Volume (SSV):

• the SSV, a mounted snapshot of the read-only System volume named Macintosh HD, which forms the root of the boot file system,
• the writable Data volume, by default on the internal disk named Macintosh HD – Data, which is normally hidden from view at /System/Volumes and accessed via firmlinks,
• Preboot, a small volume of around 40-50 MB,
• Recovery, the Recovery Volume, of around 500 MB,
• VM, containing virtual memory caches, which is upwards of 20 KB depending on use.

Note that Apple Silicon Macs don’t use EFI, and therefore may not have EFI partitions at the top level of each disk. That will only become clear when Apple ships its first production systems.

Folder layout

With a single startup volume, High Sierra and Mojave have straightforward layouts of folders from the root /.

Catalina and Big Sur (on Intel, at least) divide the major folders between their System and Data volumes. The System volume forms the root /, from which there are multiple firmlinks which join the two volumes into what appears to be a single volume both in the Finder and Terminal. A simplified integrated view of the resulting boot Volume Group is shown below.

and in this PDF for you to tear out and keep: CatalinaIntSimple

In that diagram, folders which are on the System volume (or SSV) are shown in blue, and those on the Data volume in green. Those in red are firmlinked from the System volume to that folder on the Data volume. This creates the illusion of a single, integrated volume which is actually composed of the two melded together.

There are several important folders which merit special consideration.

The top-level Applications folder is actually a firmlink to user apps on the Data volume. The Finder melds that with read-only apps installed in macOS at /System/Applications, making bundled and user apps appear to be in a single folder, which they actually aren’t. Try to trash one of the bundled apps like Calculator, or inspect its real path in the Get Info dialog, and that will be apparent.

Mutable system files can’t be installed on the read-only System volume, so are normally firmlinked to folders on the Data volume. Among the most important of these are the several folders in /private, and /usr/local in which you can install your own command tools and the like.

The Data volume itself is accessible through its mountpoint at /System/Volumes/Data, and contains the contents of the top-level Users folder, with Home folders and more.

Firmlinks

Firmlinks are similar in some respects to traditional symbolic links, but are only made between folders, work in both directions, and with a little added magic effectively merge the contents of two linked folders. For example, the /Users directory on the read-only system volume contains some directories in /Shared. As /Users is a firmlink, the directories there are merged with those in the /Users/Shared directory on the writable (Data) volume. Further details about volume groups and the file system magic in Catalina is in this Carbon Copy Cloner KB article.

The current list of system firmlinks taken from /usr/share/firmlinks is:
/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
/private <-> private
/usr/local <-> usr/local
/usr/libexec/cups <-> usr/libexec/cups
/usr/share/snmp <-> usr/share/snmp
in each case shown as the system volume path and the Data volume path which are firmlinked.

You can also create your own synthetic firmlinks, which appear at root volume level and link to folders or symbolic links on the Data volume. These are stored in an /etc/synthetic.conf file, which is documented in man synthetic.conf. Rich Trouton has published an excellent tutorial on how to do this. Users who previously had their own custom folders at the root level of the boot volume can use this to create the same effect in Catalina and Big Sur.

Paths

The standard system firmlinks mean that, for most users and most purposes, you shouldn’t have to look anywhere different, or change the paths you use in Terminal. However, if you access anything for which there isn’t a convenient firmlink, you may find that its effective path has now changed – hence these new roadmaps, to help you see where things can now be found.

In Terminal, when you want to run a command tool which you installed in the /usr/local/bin directory, you might call it using the command /usr/local/bin/mytool. In Catalina, the firmlink between the /usr/local folder on the System volume takes that path through to the correct folder on the Data volume, so you don’t have to change the path to /System/Volumes/Data/usr/local/bin/mytool.

One valuable trick for always using the right path in Terminal is to locate the folder or file in a Finder window, and drag and drop that into the command line. macOS then magically performs any path conversions for you. You may also find my utility Precize useful, as it gives paths, inode numbers, and a great deal more.

Reference layouts

These are full layouts for Catalina, which currently also apply to Big Sur running on Intel Macs.

The System volume:

available here as a PDF: Catalina System Volume

The Data volume:

available here as a PDF: Catalina Data Volume

Integrated:

available here as a PDF: Catalina Volume Group