Reading Apple’s APFS documentation, you’d think it would be very hard for any user to reach its limits. However, buried away in those pages are some which you could readily reach. And in the version of Disk Utility shipped with Mojave, they’re even easier to hit. This article explains where ordinary users can run into trouble with APFS containers and volumes, on both physical disks and in disk images.

Because APFS is rather more complex than HFS+ in the way that it handles space on disks, I remind you that each disk is divided into one or more APFS containers which don’t share space, then within each container there are one or more volumes which share the space within their container.

APFS limits the number of volumes which can exist within each container. The absolute maximum is 100, which is hardly likely to be reached unless you’re doing very peculiar things. However, there’s a smaller limit which is more likely to come into play: in any given container, the maximum number of volumes is the size of that container divided by 512 MiB, rounded up to the nearest integer. So if your container is 1.1 GiB in size, the maximum number of volumes it can support is not 100, but only 3.

The documentation gives two other limits which are of importance: the minimum size of a container is 1.048576 MB (1048576 bytes), which would therefore be able to contain just a single volume:
“NX_MINIMUM_CONTAINER_SIZE
The smallest supported size, in bytes, for a container.
#define NX_MINIMUM_CONTAINER_SIZE 1048576
This value is slightly less that the capacity of a floppy disk. For a container this size, statically allocated metadata takes up about a third of the available space.”

Additionally, the maximum length of an APFS volume name is 256 characters (I presume UTF-8), something I’ll not discuss further here.

Disk images

When you create a simple read-write disk image, you choose its total size, and that determines its default single container size, which in turn determines how many volumes it can support. Given the information above from the APFS documentation, you might be tempted to try a minimum disk image size of 1.1 MB, but if you enter any size below 8.4 MB, Disk Utility emits a system beep and creates its smallest disk image of 8.4 MB, with a single container of 8.4 MB, and one volume of the same size.

If you want two or more containers on a disk image, then you must create an image which is 40 MB or larger in the first place, which still only supports a single volume in each container. The smallest container which supports more than one volume is just under 600 MB, which is consistent with the formula given in the documentation. However, once you’ve created multiple volumes in a single container, you’ll be unable to increase the number of containers if the result would break the rule for the maximum number of volumes.

For example, if you create a disk image of 600 MB, the rules allow you to configure it in any of the following ways:

• one container, one volume, to which you could then add either a second container or a second volume, but not both;
• two containers, each with only one volume;
• one container, with two volumes.

This results in the anomalous situation that:

• the smallest container size is 8.4 MB when there’s only one container, but around 20 MB when there are two or more;
• the smallest volume size is 8.4 MB when there’s only one container and one volume, 20 MB when there are two or more containers, or about 300 MB when there are two or more volumes in the same container.

It’s possible to create smaller APFS disk images in Terminal, using a command such as
hdiutil create -size 1.1m -fs APFS test2.dmg
which creates one of only 1.1 MB quite happily, with a container of only 1.1 MB, and a single volume of 1.1 MB too.

The command tool diskutil advises different limits. The command
diskutil resizeContainer [diskref] limits
where [diskref] is the name of an APFS Physical Store partition such as disk7s1, returns four limits for the container size on any disk. For example, when used on the single default container on an APFS disk image of 100 MB, it returns
Resize limits for APFS Physical Store partition disk7s1:
Current Physical Store partition size on map: 100.0 MB (99983360 Bytes)
Minimum (constrained by file/snapshot usage): 4.2 MB (4194304 Bytes)
Recommended minimum (if used with macOS): 100.0 MB (99983360 Bytes)
Maximum (constrained by partition map space): 100.0 MB (99983360 Bytes)

What isn’t perhaps immediately obvious here is that these limits apply to the existing container, not any newly-created container. However, attempting to reduce the size of the existing container to anything less than about 18 MB results in failure in Disk Utility because the intended size is considered too small for an empty container.

The only recent article published by Apple which appears to detail disk images in Mojave doesn’t mention any of these limitations.

Physical disks

Few physical storage media are now smaller than 8 GB, and it’s unusual to leave part of that unallocated to a container. As a result, few of the constraints encountered in smaller disk images are likely to apply to physical storage. However, when partitioning storage into containers, Disk Utility initially claims the smallest container size is 8.39 MB rather than the 1.05 MB set by APFS. The app may on occasion claim that its minimum size is 2.1 MB, but steadfastly sticks to 8.39 MB whenever it matters.

Unfortunately, when you ask Disk Utility to split a container, it then insists that the smallest container it can create when splitting 250 GB is 167.8 MB, which isn’t close to the minimum container size of 8.39 MB it claimed earlier, nor that of 1.05 MB claimed in the APFS documentation.

With a little fiddling, I was able to get Disk Utility to add a new container of only 20 MB in size. As with any other container smaller than 512 MiB, this supports only a single volume.

Adding a second volume to a 250.6 GB container (which should support 100 volumes in total) returned an error 118, but this time the new volume was created, just left unmounted. Mounting it manually showed that it had apparently been created correctly after all. Adding a further 8 volumes to that container worked as expected, each without error and being correctly mounted.

Further testing confirmed that the rule given in the APFS documentation for the maximum number of volumes in any given container is respected by Disk Utility.

Consulting diskutil was also confusing. For the 250 GB SSD under test, this returned
Resize limits for APFS Physical Store partition disk5s2:
Current Physical Store partition size on map: 250.8 GB (250790436864 Bytes)
Minimum (constrained by file/snapshot usage): 167.8 MB (167772160 Bytes)
Recommended minimum (if used with macOS): 26.8 GB (26843545600 Bytes)
Maximum (constrained by partition map space): 250.8 GB (250790436864 Bytes)
which is consistent with one of the figures returned by Disk Utility, but not the test result, which successfully created a container of only 20 MB in size. It’s also unclear why the recommended minimum size is so large when the container to be resized is still empty.

When working with freshly-formatted external storage of 250 GB capacity, the smallest container size can be given as 8.39 MB, 20 MB, or 167.8 MB, as Disk Utility chooses, and the smallest volume size can be anything similar. None of these matches any limit I can find in the APFS documentation.

Summary

The smallest container size in APFS is claimed to be 1.05 MB, but that’s only attainable in disk images through hdiutil; in practice, using Disk Utility, it’s more likely to be 8.4 MB, but could be as large as 167.8 MB on a 250 GB SSD.

The absolute maximum number of volumes in any given APFS container is 100; however, a smaller limit applies to containers smaller than about 52 GB, of the size of the container divided by 512 MiB, rounded up to the nearest integer. Because of the complex lower limits on container size, no simple lower limit exists to the size of APFS volumes.

Neither Disk Utility nor diskutil help the user to select small container sizes reliably, and they’re only consistent with Apple’s stated limits for the number of volumes which can be created within a container. The APFS documentation doesn’t explain how to calculate the minimum container size which is enforced by Disk Utility. Trying to detect a consistent pattern in minimum container sizes remains a mystery to me.

All tests were carried out on macOS Mojave 10.14.6 using APFS build 945.275.7.