How to Configure Core Storage, APFS Snapshots, and Time Machine Local Snapshots in macOS Terminal

Apple File System (APFS), introduced to replace the legacy HFS+ format, incorporates advanced storage management capabilities built around a copy-on-write (CoW) design. Among its most powerful enterprise features is the native implementation of APFS snapshots—point-in-time, read-only instances of a volume that capture its complete filesystem state without duplicating physical data blocks. Time Machine relies extensively on these local snapshots to provide rapid recovery points before external backups are dispatched.

For systems administrators, forensic analysts, and macOS power users, interacting with APFS snapshots via the Terminal using diskutil and tmutil unlocks granular control over storage reclamation, system rollback, and forensic mounting that the standard graphical user interface obscures.

Architectural Overview: APFS Copy-on-Write and Snapshot Mechanics

Traditional filesystem snapshots often required allocating dedicated block maps or duplicate volume containers. In contrast, APFS embeds snapshots directly into the container’s B-tree metadata catalog:

Layer / Mechanism	Architectural Function	Storage Impact
APFS Container	Shared storage pool hosting multiple virtual APFS volumes (System, Data, Preboot, Recovery).	Space is dynamically shared across all volumes in the container.
Copy-on-Write (CoW)	Modifications allocate new storage blocks rather than overwriting existing blocks in place.	Zero initial overhead upon snapshot creation.
Snapshot Pointer	Locks the root inode tree and file extent references at an exact transactional checkpoint.	Consumes only metadata bytes (fractions of a kilobyte) at inception.
Divergence Accumulation	As files are edited or deleted on the live volume, original blocks are retained exclusively for the snapshot.	Disk footprint expands strictly in proportion to modified/deleted data volume.
Local Snapshot Retention	Automated purging daemon evaluates container free space and purges aging snapshots under disk pressure.	Managed dynamically by backupd and apfsd.

Listing and Inspecting APFS Snapshots via Terminal

macOS exposes two distinct command-line utilities for querying snapshots: diskutil apfs (which provides direct container-level filesystem insights) and tmutil (which monitors Time Machine integration).

Step 1: Identify Volume Identifiers

Query your active partition layout to confirm the exact mount identifier for your user data volume:

# List all disks and APFS containers
diskutil list

# Query APFS volume identifiers specifically
diskutil apfs listVolumes

On macOS Catalina and later, the operating system separates the cryptographically sealed system volume (e.g. Macintosh HD / disk3s1) from the mutable data volume (e.g. Macintosh HD - Data / disk3s5). Local snapshots created by Time Machine are typically bound to the Data volume.

Step 2: Enumerate Volume Snapshots

To inspect all existing snapshots anchored to your data volume, execute:

# Enumerate snapshots using diskutil
diskutil apfs listSnapshots /System/Volumes/Data

# Alternatively, list Time Machine local snapshots specifically
tmutil listlocalsnapshots /System/Volumes/Data

The command outputs each snapshot’s unique metadata attributes:

• Snapshot Name: e.g. com.apple.TimeMachine.2026-10-23-143022.local
• Snapshot UUID: A persistent 128-bit cryptographic identifier.
• Purgeable Space: The physical disk capacity that would be immediately recovered if the snapshot were purged.

Creating Manual Snapshots with diskutil and tmutil

Administrators frequently create manual snapshots before installing untrusted kernel extensions, major operating system upgrades, or massive directory restructuring.

Method 1: Creating a Time Machine Local Snapshot via tmutil

Using tmutil ensures the snapshot complies with system lifecycle retention policies and integrates into the macOS Time Machine recovery interface:

# Create a local Time Machine snapshot of the root/data container
tmutil localsnapshot

# Verify confirmation message
# Created local snapshot with date: 2026-10-24-051930

Method 2: Creating an Arbitrary Named APFS Snapshot via diskutil

If you require a custom administrative label independent of Time Machine, use diskutil apfs directly (requires root privileges):

# Create a named snapshot before running maintenance
sudo diskutil apfs createSnapshot /System/Volumes/Data "PreMigrationBackup_20261024"

Mounting and Inspecting Snapshots in Read-Only Mode

One of the most practical capabilities of APFS snapshots is the ability to mount any previous point-in-time snapshot to an arbitrary directory. This enables forensic auditing or targeted recovery of individual files without restoring the entire volume.

Step 1: Create a Mount Directory

# Create a temporary directory in /tmp or /Volumes
sudo mkdir -p /tmp/snapshot_mount

Step 2: Mount the Snapshot Using mount_apfs

Use the mount_apfs binary, supplying the snapshot name or UUID along with the source volume device identifier:

# Mount the snapshot in read-only mode (-s flag specifies snapshot name)
sudo mount_apfs -s "com.apple.TimeMachine.2026-10-23-143022.local" -o ro /dev/disk3s5 /tmp/snapshot_mount

Step 3: Browse and Recover Specific Files

The mounted directory now reflects the exact filesystem tree as it existed when the snapshot was frozen:

# Browse the filesystem state
ls -la /tmp/snapshot_mount/Users/username/Documents

# Copy a damaged or deleted configuration file back to live storage
cp /tmp/snapshot_mount/Users/username/.zshrc ~/recovered_zshrc

Step 4: Unmount the Snapshot

Once data extraction is complete, unmount the synthetic volume cleanly:

# Unmount using diskutil
sudo diskutil unmount /tmp/snapshot_mount

# Remove the temporary mount directory
sudo rmdir /tmp/snapshot_mount

Deleting and Thinning Local Snapshots to Reclaim Disk Space

When storage capacity dwindles or when large deletion operations (such as clearing a 100 GB virtual machine image) fail to register as free disk space, active snapshots holding references to the deleted blocks are the primary culprit.

Step 1: Automated Thinning via tmutil

The tmutil thinlocalsnapshots command requests the system purge snapshots up to a designated byte threshold with a specified urgency level:

# Thin snapshots to release approximately 50 GB (50000000000 bytes)
# Urgency: 1 (conservative) to 4 (aggressive/immediate)
tmutil thinlocalsnapshots /System/Volumes/Data 50000000000 4

Step 2: Deterministic Manual Snapshot Deletion

To eliminate a specific snapshot identified by date or UUID:

# Delete a specific Time Machine local snapshot by timestamp
tmutil deletelocalsnapshots 2026-10-23-143022

# Delete an arbitrary APFS snapshot using diskutil and its UUID
sudo diskutil apfs deleteSnapshot /System/Volumes/Data -uuid 7F9E2A1B-3C4D-5E6F-8A9B-0C1D2E3F4A5B

Troubleshooting APFS Snapshot and Storage Discrepancies

Consult this diagnostic matrix to resolve common snapshot anomalies and storage reporting conflicts:

Symptom	Root Cause	Remediation Procedure
Deleting large files does not increase “Available” storage in Finder.	Blocks remain locked by one or more local APFS snapshots retaining historical extents.	Run tmutil listlocalsnapshots /System/Volumes/Data and purge older entries using tmutil thinlocalsnapshots.
mount_apfs fails with “Resource busy” or “Device not configured”.	Target mount point directory is invalid, or the underlying APFS volume device node is incorrect.	Verify device identifier with diskutil apfs listVolumes. Ensure you are targeting the exact synthetic node (e.g. disk3s5) and that the mount point directory is empty.
tmutil localsnapshot returns “Local snapshots are not enabled”.	Time Machine automatic backups are disabled system-wide.	Re-enable automatic backups via sudo tmutil enable, or use sudo diskutil apfs createSnapshot for standalone creation.
Disk Utility displays high “Purgeable” storage that the OS refuses to clear.	macOS deferral algorithm waits until physical storage hits 80–90% threshold before triggering automated pruning.	Force immediate truncation using tmutil thinlocalsnapshots /System/Volumes/Data 99999999999 4.

Mastering APFS snapshots from the command line provides administrators with rigorous control over macOS storage economics, rapid disaster mitigation, and reliable non-destructive system testing.