tmutil: Control Time Machine From Terminal

Time Machine's settings pane is deliberately simple — which is fine until you want to kick off a backup from a script, exclude a folder programmatically, or find out what the spinning backup icon is actually doing. tmutil is the command-line control panel for all of it, on every supported version of macOS.

Start, stop, and watch a backup

# kick off a backup right now
tmutil startbackup

# undo: cancel the running backup
tmutil stopbackup

# what Time Machine is doing at this moment
tmutil status

startbackup returns immediately while the backup runs in the background; add -b (block) if a script should wait for completion. status prints a dictionary — the useful fields are Running, the current phase (like Copying or ThinningPostBackup), and Percent. Stopping a backup mid-run is safe: Time Machine simply resumes the work next cycle.

Manage exclusions from the command line

Excluding folders in System Settings means clicking through a file picker. tmutil does it in one line, which also makes it scriptable:

# stop backing up a folder (exclusion travels with it)
tmutil addexclusion ~/VirtualMachines

# undo: include it again
tmutil removeexclusion ~/VirtualMachines

# check any path's status
tmutil isexcluded ~/VirtualMachines

The default exclusion is "sticky" — it's attached to the item itself, so it follows the folder if you move or rename it. Add the -p flag (with sudo) for a fixed-path exclusion like the ones the System Settings list creates. Sticky exclusions don't appear in that list, so isexcluded is the only way to audit them — worth remembering before you conclude Time Machine "missed" something.

See what's been backed up

# every completed backup on the current destination
tmutil listbackups

# just the newest one
tmutil latestbackup

# where backups are going, and destination health
tmutil destinationinfo

If listbackups complains about permissions, grant Terminal Full Disk Access in System Settings → Privacy & Security — backup metadata is protected data. A quick sanity check that backups are actually recent: compare the timestamp in the latestbackup path against today's date.

Local snapshots

Between visits to the backup disk, Time Machine stores hourly snapshots on the internal drive — it's why restores sometimes work with no disk attached, and where mystery "purgeable" space often lives.

# create a snapshot right now
tmutil localsnapshot

# list snapshots on the boot volume
tmutil listlocalsnapshots /

Snapshots age out automatically after about 24 hours, and macOS deletes them on its own when disk space runs low, so they rarely need managing. A deletelocalsnapshots subcommand exists for reclaiming space immediately, but treat it as a last resort — each snapshot you delete is a restore point you no longer have.

Pause and resume automatic backups

# pause automatic backups (manual ones still work)
sudo tmutil disable

# undo: resume the automatic schedule
sudo tmutil enable

Pausing is occasionally right — during a huge file reorganization, say, so Time Machine doesn't spend hours copying files you're about to move again. If the goal is reclaiming space rather than pausing, tmutil thinlocalsnapshots / 10000000000 4 asks macOS to free roughly 10 GB by thinning local snapshots — gentler than deleting them outright, because the system chooses what to sacrifice. Whatever you disable, remember to re-enable: a paused Time Machine fails silently, and the menu bar icon is the only tell.

If any of these commands complain that no destination is configured, set one first — in System Settings → General → Time Machine, or directly with sudo tmutil setdestination /Volumes/Backups.

Put it on a schedule

Because tmutil startbackup is just a command, you can trigger backups whenever you like — before a big update, or nightly via a LaunchAgent. Our guide to scheduling tasks with launchd shows the pattern.