How to Use the tmutil Command in macOS Terminal to Manage Time Machine Backups

In macOS systems engineering and automated fleet management, maintaining reliable disaster recovery backups is paramount. While the native Time Machine graphical interface in System Settings provides basic toggles for consumer workflows, advanced administrative operations—such as managing Apple File System (APFS) local snapshots, auditing backup health via SSH, automating path exclusions, comparing filesystem drift, and forcing headless backups—require the native tmutil command-line utility. Mastering tmutil enables Mac administrators and power users to inspect, prune, script, and troubleshoot Time Machine backups with surgical precision.

Understanding the tmutil Command Architecture

The tmutil executable interfaces directly with the Time Machine framework daemon (backupd) and the APFS snapshot subsystem. The table below delineates the essential command verbs and their operational behaviours:

Command Verb	Primary Technical Function	Disk & System Impact	Administrative Context
startbackup	Initiates an ad-hoc or scheduled backup session.	Spawns backupd; reads live APFS filesystem metadata.	Forcing pre-deployment or pre-upgrade snapshot backups.
status	Emits real-time JSON/plist progress of an active backup.	Read-only; queries running daemon memory.	Monitoring backup phase, percent complete, and byte throughput.
localsnapshot	Creates an instantaneous read-only APFS point-in-time snapshot.	Zero write penalty; creates metadata pointers on root container.	Creating rapid rollback points prior to risky software installs.
listlocalsnapshots	Enumerates all APFS snapshots residing on a specified volume.	Read-only disk query.	Auditing local storage consumption and snapshot lifecycles.
compare	Analyzes differences between a specific backup and current disk state.	High read I/O; cross-examines file attributes and hashes.	Investigating unauthorized filesystem alterations or forensic auditing.

Triggering and Monitoring Headless Backups

When administering remote Mac servers or executing deployment scripts over SSH, initiating backups headlessly ensures data protection without relying on GUI interaction.

1. Starting and Halting Backups

To launch a backup in the background while respecting battery and thermal throttling limits:

tmutil startbackup --auto

To force an immediate, high-priority backup that executes regardless of AC power status:

sudo tmutil startbackup --block

The --block flag keeps the terminal session open until the backup fully concludes, making it ideal for integration into sequential shell automation scripts.

To terminate an active or stalled backup session:

sudo tmutil stopbackup

2. Monitoring Active Backup Progress

To inspect whether Time Machine is currently transferring data, run:

tmutil status

The output returns a structured block displaying the active operational phase (e.g., MountingBackupVolume, FindingChanges, or Copying), total bytes transferred, and estimated time remaining.

Managing APFS Local Snapshots

Even when your external backup drive is unplugged, macOS creates APFS local snapshots on the internal drive. While useful for rapid file restoration, unchecked local snapshots can exhaust internal storage.

1. Creating an Instantaneous APFS Snapshot

To capture the current state of your system disk prior to running major operating system updates or testing experimental developer toolchains:

tmutil localsnapshot

Returns: Created local snapshot with date: 2026-10-23-171500.

2. Listing and Purging Local Snapshots

To list all local snapshots stored on the primary APFS boot container:

tmutil listlocalsnapshots /

To delete a specific snapshot by timestamp:

sudo tmutil deletelocalsnapshots 2026-10-23-171500

To purge local snapshots in bulk when disk space is starved and Time Machine refuses to free purgeable storage:

sudo tmutil thinlocalsnapshots / 10000000000 4

This command instructs macOS to reclaim approximately 10 GB of space from volume / using urgency level 4 (maximum aggressiveness).

Configuring Backup Destinations and Path Exclusions

Customising what Time Machine backs up and where it archives data avoids wasting storage on virtual machine disks or ephemeral caches.

1. Managing Storage Destinations

To view currently configured backup targets and their unique IDs:

tmutil destinationinfo

To attach a new external APFS volume or SMB network share as a backup target:

sudo tmutil setdestination -p "afp://user:[email protected]/TimeMachine"

2. Adding and Inspecting Path Exclusions

To permanently exclude massive cache directories (such as Xcode DerivedData or Docker containers) from future backups:

# Add a persistent path exclusion
sudo tmutil addexclusion -p "/Users/developer/Library/Developer/Xcode/DerivedData"

# Verify if a specific directory is excluded
tmutil isexcluded "/Users/developer/Library/Developer/Xcode/DerivedData"

# Remove an existing exclusion
sudo tmutil removeexclusion -p "/Users/developer/Library/Developer/Xcode/DerivedData"

The -p switch enforces a path-based exclusion that persists even if the folder is deleted and recreated, contrasting with standard file-quarantine sticky bit exclusions.

Comparing Filesystem Drift with tmutil compare

To evaluate what changes have occurred on your Mac since the last completed Time Machine backup, execute:

tmutil compare

To compare a specific folder against the most recent backup on disk:

tmutil compare "/Applications"

The utility outputs a line-by-line diff indicating modified files (+, -), altered file sizes, and permission discrepancies.

Troubleshooting Common tmutil and Backup Bottlenecks

When Time Machine exhibits errors or refuses to complete scheduled passes, apply the following triage steps:

• Backup Stalled at “Finding Changes”: Often caused by corrupted FSEvents (File System Events) databases. Reset Time Machine’s indexing state by running:

  sudo mdutil -E /Volumes/TimeMachineBackupDrive

• Operation Not Permitted (Error 1): Even root users running sudo cannot modify certain Time Machine directories due to macOS System Integrity Protection (SIP) and Transparency, Consent, and Control (TCC) restrictions. Ensure your Terminal application is granted Full Disk Access under System Settings > Privacy & Security.
• Time Machine Target Failing to Mount over SMB: Verify network credentials and ensure the remote NAS supports APFS over SMB or Apple Time Machine SMB extensions (fruit:time machine = yes in Samba configuration).