APFS, the official abbreviation for the Apple File System, first appeared in a pre-release preview with macOS Sierra, and was initially released with iOS 10.3 on 27 March 2017, then in macOS 10.13 High Sierra the following September. It has since undergone rapid evolution, with the addition of features such as system volume groups and firmlinks to support Catalina and the Signed System Volume of Big Sur and later. This article outlines its key components, versions, and their compatibility as they affect Mac users.

Components

• apfs.kext, its kernel extension,
• apfs.fs, the file system itself, a bundle containing its executables,
• APFS.framework and apfs_boot_mount.framework, private frameworks used by system code.

In any given release of macOS, these all bear the same version number, given as [major].[minor].[patch], making it simple to check consistency.

Utilities provided for users to work with APFS file systems are Disk Utility, which itself calls executables such as fsck_apfs, and the following command tools, documented in their respective man pages:

• apfs.util
• diskutil
• fsck_apfs
• mount_apfs
• newfs_apfs

Disk Utility uses a different version numbering system from APFS, but generally calls tools in the current version of APFS to do its dirty work.

APFS file systems, each forming a volume, are stored inside APFS containers, themselves partitions on storage using a GUID partition map (GPT format). File systems within a container thus share the storage space allocated to that container. Containers have a fixed size (although repartitioning a disk should be performed non-destructively when possible), but the volumes within them vary in size according to their contents. There are options to constrain volume size, if desired.

This is summarised in the diagram below, and described in more detail here.

APFS snapshots consist of a copy of the file system of a volume at the instant the snapshot was made, together with all data within that volume that has changed since that snapshot was made. This enables that volume’s file system metadata to be rolled back to the state of the volume and its contents at the time the snapshot was made.

APFS may report stored information about which tools were used to create and modify file systems, such as
The volume Macintosh HD - Data was formatted by diskmanagementd (2142.81.1) and last modified by apfs_kext (2142.140.9).
That volume was last formatted by APFS version 2142.81.1 in macOS 13.2, and its file system metadata were last changed by APFS version 2142.140.9 in macOS 13.5 or 13.5.1.

Versions

APFS major version numbers change with each major version of macOS:

• macOS 10.12 has APFS version 0.3 or 249.x.x
• 10.13 has 748.x.x
• 10.14 has 945.x.x
• 10.15 has 1412.x.x
• 11 has 1677.x.x
• 12 has 1933.x.x until 12.2, thereafter 1934.x.x.
• 13 has 2142.x.x.

Minor version numbers increment according to the minor version of macOS, and patch numbers wander without apparent pattern:

• macOS 10.13 went through 748.1.46 (10.13) to 748.51.0 (10.13.4 and later)
• 10.14 went from 945.200.129 (10.14) to 945.275.9 (10.14.6 with SU 2020-005)
• 10.15 went from 1412.11.7 (10.15) to 1412.141.1 (10.15.6 and .7)
• 11 went from 1677.50.1 (11.0.1) to 1677.141.2 (11.6)
• 12 went from 1933.41.2 (12.0.1) to 1934.141.2 (12.5)
• 13 went from 2142.41.2 (13.0) to 2142.140.9 (13.5).

Changing version numbers thus aren’t any indication of the scope or magnitude of changes made to APFS. As Apple seldom provides any information on changes made to APFS, it’s anyone’s guess as to what is going on.

Known milestones

In release versions of APFS:

• version 748.21.6 (macOS 10.13.1) fixed problems in snapshots
• versions 945.275.8 and 945.275.9 (macOS 10.14 security updates 2 and 2020-005) fixed unspecified bugs, probably vulnerabilities
• version 1412.11.7 (macOS 10.15) introduced system volume groups and firmlinks
• version 1412.120.2 (macOS 10.15.5) fixed a serious bug preventing the transfer of very large amounts of data to RAID volumes
• version 1933.41.2 (macOS 12.0.1) is believed to have introduced a trim-on-mount feature that stores trimmed UDRW disk images as sparse files
• version 1934.101.3 (macOS 12.3) brought an unexpected major version increment, but no reason has been given.

Compatibility

The basic safety principle with APFS is to use the most recent available version of its tools when working with the file system. If your Mac can boot in both Ventura (APFS version 2142.140.9) and Catalina (1412.141.1), then you should prefer version 2142.140.9 tools when working with its APFS volumes and containers. Although APFS is designed and implemented to provide as much forward compatibility as possible, backward compatibility is preferred.

There are some combinations that do cause problems. Versions of APFS prior to 1412.11.7 (Catalina) don’t understand system volume groups or firmlinks, nor the SSV of macOS 11 and later. Using fsck_apfs from such an old version on a macOS 13 system volume group isn’t a good idea.

This demands close attention when using dual-boot systems, but is most demanding when booting into Recovery. Normal behaviour is for a Mac to enter the paired recovery volume for the system volume group that it has just been running from, but some combinations of macOS and hardware may not always do that, and it’s easy for the user to become confused. Virtual APFS file systems inside disk images and sparse bundles also merit caution when being accessed from older versions of macOS.

Aside from the use of file system utilities, the use of volumes formatted using different versions of APFS should be free of trouble, even when there’s a wide gap between the versions. When mounted normally (in read-write mode), many volumes undergo initial trim by APFS, depending on the storage medium. This is particularly beneficial for disk images from Monterey onwards, as they are stored as sparse files when possible, and that initial trim should reduce the space taken on disk to the minimum required for their stored data.

macOS has many background services that will quickly change the file system metadata, such as Spotlight indexing and maintenance of .DS_Store files, even before any app has touched the files on a volume. APFS seems able to ensure that those changes are both stable and compatible across a wide range of versions of APFS. However, the only way to bring a volume or whole container fully up to date with a newer version of APFS than the one used to format it, is to format that volume or container using the latest APFS tools and restore their contents. There seems little point in ever doing that.

Summary

• APFS has changed greatly since it was introduced, and a new version accompanies each minor release of macOS.
• APFS version information can be useful when investigating file system problems.
• Care must be taken to avoid using older APFS tools, including Disk Utility, on newer versions of APFS. This is most critical in Recovery mode.
• Otherwise interoperability between versions is normally excellent, and incompatibilities rare.