When you read Apple's APFS documentation, you would think it would be very difficult for any user to reach their limits. However, there are some that you can easily reach, buried on these pages. And in the Disk Utility version that comes with Mojave, they are even easier to hit. This article explains how common users can have problems with APFS containers and volumes, both on physical disks and in disk images.
Because APFS is quite more complex than HFS + in that it handles disk space, I remind that each disk is divided into one or more APFS containers that does not share space, so within each container there is one or more volumes that share space within their container.
APFS limits the number of volumes that can exist in each container. The absolute maximum is 1
The documentation provides two other limits that are significant: the minimum size of a container is 1.048576 MB (1048576 bytes ), which can therefore only contain a single volume:
The smallest supported size, in bytes, for a container.
#define NX_MINIMUM_CONTAINER_SIZE 1065 value is slightly less than disk capacity. For a container of this size, statically assigned metadata takes about a third of the available space. ”
In addition, the maximum length of an APFS volume name is 256 characters (I assume UTF-8), which I will not discuss further here.
When you create a single read-write disk image, you select the total size and determine the default size for a single container, which in turn determines how many volumes it can support. Given the above information from the APFS documentation, you may be tempted to try a minimum disk size of 1.1 MB, but if you specify a size below 8.4 MB, Disk Utility sends a system beep and creates the 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 in a disk image, you need to create an image that is 40 MB or larger initially, which still supports only a single volume in each container. The smallest container that supports more than one volume is just under 600 MB, which is in accordance with the formula given in the documentation. However, once you have created multiple volumes in a single container, you will not be able to increase the number of containers if the result will break the rule for the maximum number of volumes.
For example, if you create a 600 MB disk image, the rules allow you to configure it in one of the following ways:
- a container, one volume, which you can then add another container or volume, but not both.
- two containers, each with only one volume;
- a container, with two volumes.
This results in the anomalous situation that:
- the smallest container size is 8.4 MB when there is only one container, but around 20 MB when there are two or more;
- the smallest volume size is 8.4 MB when there is 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 is possible to create smaller APFS disk images in Terminal, using a command like
hdiutil create-size 1.1m -fs APFS test2.dmg
that creates one of only 1.1 MB quite happy, with a container of only 1.1 MB, and a single volume of 1.1 MB as well.
The command tool
disputil has different limits. The
diskutil resizeContainer [diskref] command restricts
[diskref] is the name of an APFS Physical Store partition like disk7s1, returns four container size limits on any disk. For example, when applied to a single standard container on a 100 MB APFS disk image, it returns
Resize APFS Physical Store Partition Size Limits disk7s1:
Current Physical Store Partition Size on the Map: 100.0 MB (99983360 Bytes)
Minimum (limited by file / still image usage): 4.2 MB (4194304 bytes)
Recommended minimum (if used with macOS): 100.0 MB (99983360 Bytes)
Maximum (limited by partition map space): 100.0 MB (99983360 Bytes)
What may not be immediately apparent here is that these limits apply to the existing container, not any newly created container. However, attempts to reduce the size of the existing container to something less than 18 MB result in errors in Disk Utility because the intended size is considered to be too small for an empty container.
The only recent article published by Apple that seems to detail disk images in Mojave does not mention any of these limitations.
Few physical storage media is now less than 8 GB, and it is uncommon to leave part of it unassigned to a container. As a result, some of the limitations that arise in smaller disk images are likely to apply to physical storage. However, when partitioning storage into containers, Disk Utility originally claims that the smallest container size is 8.39 MB instead of 1.05 MB set by APFS. The app may occasionally claim that the minimum size is 2.1 MB, but sticks to 8.39 MB when it matters.
Unfortunately, when you ask Disk Utility to split a container, it then insists that the smallest container it can create when you split 250 GB is 167 , 8 MB, which is nowhere near the 8.33 MB minimum container size claimed earlier, nor the 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 all other containers smaller than 512 MiB, this only supports a single volume.
Adding another volume to a 250.6 GB container (which will support 100 volumes in total) gave an error 118, but this time the new volume was created, only without mounting. Mounting it manually showed that it apparently was created correctly after all. Adding an additional 8 volumes to the container worked as expected, each without errors and correctly fitted.
Further testing confirmed that the rule given in the APFS documentation for the maximum number of volumes in a given container is respected by Disk Utility.
discutile was also confusing. For 250 GB SSD under test, this returned
Resize APFS Physical Store Partition Resize disk5s2:
Current physical store partition size on map: 250.8 GB (250790436864 Bytes)
Minimum (limited by file / still image usage) : 167.8 MB (167772160 Bytes)
Recommended minimum (if used with macOS): 26.8 GB (26843545600 Bytes)
Maximum (limited by partition map space): 250.8 GB (250790436864 Bytes)
which is consistent with one of the numbers returned by Disk Utility, but not the test result, which successfully created a container of only 20 MB in size. It is also unclear why the recommended minimum size is so large when the container to be changed is still empty.
When working with newly formatted external storage with 250 GB capacity, the smallest container size can be given as 8.39 MB, 20 MB, or 167.8 MB, as Disk Utility selects, and the smallest volume size can be something similar. None of these matches any limit I find in the APFS documentation.
The smallest container size in APFS is claimed to be 1.05 MB, but it is only obtainable on disk images through
hdiutil ; In practice, by using Disk Utility, it is more likely to be 8.4 MB, but can be as large as 167.8 MB on a 250 GB SSD.
The absolute maximum number of volumes in a given APFS container is 100; However, a smaller limit applies to containers less than approx. 52 GB, of the size of the container divided by 512 MiB, rounded to the nearest integer. Due to the complex lower container size limits, there are no simple lower limits for the size of the APFS volumes.
Neither Disk Utility nor
diskutil help the user to select small container sizes reliably, and they are only in accordance with Apple's stated limits on the number of volumes that can be created in a container. The APFS documentation does not explain how to calculate the minimum container size enforced by Disk Utility. Trying to discover a consistent pattern in minimal container sizes is still a mystery to me.
All tests were performed on macOS Mojave 10.14.6 using APFS build 945.275.7.