How to Use the diskutil Command in macOS Terminal to Manage APFS Containers, Volumes, and Partitions

In macOS systems administration, hardware provisioning, and forensic disk analysis, configuring storage volumes through the graphical Disk Utility application frequently hides critical structural telemetry or refuses to execute complex partitioning schemes. Apple File System (APFS), introduced as the modern storage architecture across Apple silicon and Intel Macs, revolutionised volume management by decoupling physical disk partitions from logical volume allocation through “APFS Containers” and dynamic “Space Sharing”. The native diskutil command-line utility provides the authoritative administrative interface to inspect physical block devices, construct and resize APFS containers, provision encrypted sub-volumes, and repair damaged filesystems.

APFS Container Architecture vs. Legacy Partitioning

Unlike legacy HFS+ partitioning—which carved physical platters into rigid, statically-sized boundary slices—APFS groups one or more physical partitions into a shared storage pool termed a “Container”. The table below delineates the structural hierarchy of APFS storage:

Architectural Layer	Technical Identifier	Functional Role & Capacity Allocation
Physical Storage Node	/dev/disk0 (Internal NVMe)	Raw physical hardware block device containing the GUID Partition Table (GPT).
Container Partition	/dev/disk0s2 (Apple_APFS)	Physical disk slice allocated to the APFS storage scheme.
APFS Container Pool	/dev/disk3 (Synthesized)	Virtualized storage pool that aggregates raw disk space and hosts child volumes.
APFS Logical Volume	/dev/disk3s1 (Macintosh HD)	Logical filesystem share. Multiple volumes dynamically share the container’s total free space.
Volume Roles	System, Data, Preboot, Recovery, VM	Cryptographically segregated roles supporting macOS Sealed System Volume (SSV) security.

Listing and Inspecting Storage Devices

All disk operations begin with accurate node identification. Executing destructive commands against the wrong disk identifier can wipe primary operating system volumes.

1. Enumerating All Connected Disks

To inspect physical drives, synthesized containers, and virtual disk images:

diskutil list

To view strictly the hierarchical tree of APFS containers, encrypted states, and volume roles:

diskutil apfs list

2. Querying Granular Volume Telemetry

To inspect sector sizes, solid-state SMART status, file system UUIDs, and mount points for a specific volume:

diskutil info /dev/disk3s1

Managing APFS Volumes and Dynamic Space Sharing

Because all volumes inside an APFS container share the exact same pool of free storage, adding a new volume for software testing or secondary operating systems requires no re-partitioning or free-space reallocation.

1. Adding a New APFS Volume

To create a new, unencrypted volume named Workspace inside your synthesized container (e.g., disk3):

diskutil apfs addVolume disk3 APFS "Workspace"

To provision a volume protected by native hardware-backed XTS-AES 128 cryptographic encryption:

diskutil apfs addVolume disk3 APFS "SecureData" -stdinpassphrase

The terminal securely prompts for a passphrase without echoing characters to the screen.

2. Setting Quota and Reserve Allocation Boundaries

While space sharing is automatic, administrators can define storage boundaries to prevent runaway logs from exhausting container space:

• -reserve <size>: Guarantees a minimum floor of storage that other volumes cannot claim.
• -quota <size>: Establishes a hard ceiling that the target volume cannot exceed.

diskutil apfs addVolume disk3 APFS "SandboxedApp" -reserve 20g -quota 50g

3. Deleting an APFS Volume

To permanently erase a volume and reclaim its space back to the shared container immediately:

diskutil apfs deleteVolume /dev/disk3s5

Formatting, Partitioning, and Erasing Disks

When preparing external Thunderbolt SSDs, USB drives, or disk arrays for production use, diskutil executes full formatting operations.

1. Erasing a Full Physical Drive to APFS

To initialize a complete external drive (e.g., disk4) with a GUID Partition Map and an APFS container:

diskutil eraseDisk APFS "ExternalSSD" GPT /dev/disk4

Warning: This action permanently obliterates all partition tables and data residing on disk4.

2. Resizing an APFS Container

To shrink an existing APFS container to free up raw physical space for a secondary non-APFS partition (such as ExFAT for Windows cross-compatibility):

sudo diskutil apfs resizeContainer /dev/disk0s2 400g ExFAT "WindowsShare" 100g

Mounting, Unmounting, and Ejecting Disks Safely

When software installers lock volumes or Finder reports “Disk in use”, force terminal unmounting:

• Unmount a Single Volume:

  diskutil unmount /dev/disk3s1

• Unmount All Volumes on a Physical Drive:

  diskutil unmountDisk /dev/disk4

• Eject External Media Completely (Powers Down Controller):

  diskutil eject /dev/disk4

• Mount a Volume:

  diskutil mount /dev/disk3s1

Verifying and Repairing APFS Storage Health

If volumes fail to mount, experience silent write stalls, or display filesystem corruption flags, initiate the non-destructive verification scan:

diskutil verifyVolume /dev/disk3s1

To execute a comprehensive repair across the APFS container and superblock metadata tree:

diskutil repairVolume /dev/disk3s1

This command invokes fsck_apfs under the hood, validating object maps, verifying snapshot trees, and fixing inverted b-trees.

Troubleshooting Common diskutil Errors

When operating diskutil, administrators frequently encounter specific environmental roadblocks:

• “Couldn’t unmount disk (-69888)”: Occurs when a background process (such as Spotlight mds, an open Terminal directory, or QuickLook daemon) holds open file handles on the target volume. Identify and kill the culprit process using:

  sudo lsof +D /Volumes/ExternalSSD

  Alternatively, force the unmount operation using diskutil unmountDisk force /dev/disk4.
• “APFS Container is not clean” Error During Resize: You cannot shrink an APFS container if snapshots exist that lock data blocks past the intended truncation boundary. List and purge obsolete APFS snapshots using tmutil deletelocalsnapshots before attempting container resizing.
• Cannot Delete System Volume on macOS: The boot volume group on modern macOS is sealed by a cryptographic Merkle tree (Sealed System Volume). Attempting to mutate or delete disk3s1 (System) while booted normally is blocked by System Integrity Protection (SIP). System repairs must be executed strictly from macOS Recovery Mode (Command + R or holding the power button on Apple silicon).