Apple File System (APFS) manages physical storage dynamically using shared storage containers. All volumes within an APFS container share the same pool of free disk space automatically. However, when preparing a Mac for dual-boot configurations (such as installing Linux or allocating a dedicated physical partition for Boot Camp on Intel Macs), or when managing external multi-format hard drives, you cannot simply add a new volume. You must physically resize the underlying APFS Container itself to carve out raw unallocated partition space.
While the graphical Disk Utility app can partition drives, it frequently fails with obscure errors like “Unable to resize container because APFS metadata cannot be moved.” In macOS Terminal, the native diskutil apfs resizeContainer command provides full control over sector boundaries, dry-run simulations, and error diagnostics.
Understanding Container Resizing Mechanics
Resizing an APFS container differs fundamentally from adding an APFS volume:
- Volume Addition: Creates a new logical volume inside the existing container without modifying partition boundaries. Requires zero resizing operations.
- Container Resizing (Physical): Modifies the physical GUID Partition Table (GPT) and APFS superblock structures on the physical disk. It shrinks or expands the container boundaries, leaving raw unallocated space available for new disk partitions.
Identifying Your Target Container Identifier
Before running resizing operations, locate the physical container partition identifier:
diskutil listIdentify the disk node corresponding to the physical container partition (e.g., /dev/disk0s2 or /dev/disk1s2) rather than the synthesized virtual container disk (e.g., /dev/disk3).
Checking Container Minimum Size Constraints
You cannot shrink an APFS container smaller than the total allocated data currently stored across all its child volumes, plus required APFS metadata allocation overhead. To inspect your container’s minimum allowable size, run a dry-run check:
diskutil apfs resizeContainer /dev/disk0s2 0Passing 0 as the target size triggers a non-destructive query. macOS will inspect the volume structures and return the absolute minimum size required to preserve all existing data:
Current container size: 500.0 GB
Minimum container size: 245.8 GBCommand Syntax and Options
The standard syntax for resizing an APFS container is:
diskutil apfs resizeContainer <ContainerPartitionID> <NewSize> [Format] [Name] [Size]The table below summarizes common command variations:
| Command Structure | Operational Effect | Common Scenario |
|---|---|---|
diskutil apfs resizeContainer disk0s2 300g |
Shrinks container to 300 GB; leaves remainder as unallocated free space. | Preparing unpartitioned space for Linux or Windows installers. |
diskutil apfs resizeContainer disk0s2 0 |
Queries the container and outputs minimum and maximum allowable sizes. | Non-destructive safety check before committing disk changes. |
diskutil apfs resizeContainer disk0s2 300g JHFS+ Secondary 0 |
Shrinks container to 300 GB and formats the remaining space into an HFS+ volume. | Creating a dedicated secondary partition for Time Machine or legacy storage. |
diskutil apfs resizeContainer disk0s2 0g |
Expands the container to fill all contiguous trailing unallocated disk space. | Reclaiming space after deleting a secondary partition. |
Step-by-Step: Shrinking an APFS Container Safely
- Ensure you have a recent Time Machine backup of your Mac before modifying drive geometry.
- Open Terminal (Applications > Utilities).
- Query the disk to find the physical container slice:
diskutil apfs list - Perform a minimum size check:
diskutil apfs resizeContainer disk0s2 0 - Execute the resize command specifying your desired container size (e.g., reducing a 500 GB drive to 350 GB):
diskutil apfs resizeContainer /dev/disk0s2 350g - macOS will lock the container, shrink APFS metadata structures, update the GPT partition table, and unmount/remount volumes seamlessly.
Frequently Asked Questions
Why does resizeContainer return “Error: -69531: Not enough space”?
This error occurs when the requested target size is smaller than the minimum allowable data footprint, or when APFS snapshots (such as local Time Machine snapshots) are preventing space reclamation. Delete local snapshots using tmutil deletelocalsnapshots before retrying.
Can I resize an internal startup container while booted into macOS?
Yes. macOS supports online resizing for APFS containers. However, if internal drive structures are fragmented or busy, performing the operation from macOS Recovery Mode (Cmd + R or Power button hold) provides greater reliability.