How to Manage Time Machine Using Command-Line Tools

🛠 Tools and Programming
,
1

Recommended Terms

The official GUI settings are too limited.
You’ll need to use the command line instead.

Original Article

This article was converted by SimpRead; original source: sspai.com

Time Machine is a built-in backup utility for macOS that automatically backs up files on your system and preserves historical versions of each file.

When the backup disk runs low on space, Time Machine can automatically purge older backups. However, manual cleanup may still be necessary in certain scenarios, such as:

  1. A single hard drive is shared across multiple Macs; clearing old backups from one Mac frees up space for another Mac’s backups.
  2. Freeing up disk space for storing other files.
  3. Switching to a smaller-capacity drive—for example, replacing an HDD with an SSD.
  4. Removing large, non-essential files from backups (e.g., Steam game libraries, virtual machines, iOS simulators) to reserve more backup space for critical files (e.g., personal documents), thereby preserving more historical versions of those important files.

On my NAS, Time Machine backups consumed excessive space due to the lack of configured storage quotas—negatively impacting the availability of space for other files. Thus, I began researching how to clean up Time Machine backups.

The tmutil Command-Line Tool

macOS includes the built-in tmutil command-line utility, which supports viewing backups, creating backups, deleting backups, comparing backups, and more.

Specifically, the tmutil listbackups command lists all available Time Machine backups:

$ tmutil listbackups  
/Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2019-12-21-200941  
/Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2020-01-05-221538  
/Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2020-01-19-203155

The tmutil delete command deletes a specified Time Machine backup:

$ sudo tmutil delete /Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2019-02-01-211852  
Deleting: /Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2019-02-01-211852  
Deleted (427.2M): /Volumes/Time Machine Backup/Backups.backupdb/blanboom-studio/2019-02-01-211852

With these two commands, you can conveniently incorporate them into shell scripts for batch deletion of backups.

Using Scripts to Batch-Delete Old Backups

While searching online, I discovered existing scripts designed specifically for batch-deleting old Time Machine backups. By downloading such a script and adjusting its parameters, you can perform bulk Time Machine cleanup:

I made minor modifications to this script to allow direct parameter specification at runtime. You can download the updated version via either of the following links:

To run it, simply execute tmcleanup.sh, followed by the Time Machine disk mount path, your computer name, and the number of days’ worth of backups to retain. For instance, the command below will delete all backups older than 30 days for the Mac named blanboom-studio, located under /Volumes/Time Machine Backup/Backups.backupdb:

$ sudo ./tmcleanup.sh /Volumes/Time Machine Backup/Backups.backupdb blanboom-studio 30

Using Scripts to Delete 50% of Old Backups

One of Time Machine’s standout features is its intelligent retention policy for backup versions: it preserves many versions for recent backups but gradually reduces frequency over time—for example, retaining only monthly versions for older backups.


Time Machine’s backup version retention strategy

However, Time Machine only supports weekly retention for older backups. It cannot natively implement finer-grained policies like retaining biweekly backups from one year ago—or monthly backups from one year ago.

By slightly modifying the above script, you can configure it to delete only every other backup (instead of deleting all eligible backups), effectively preserving 50% of old backups.

Of course, you may further customize or combine executions of the script to achieve alternative retention ratios—such as keeping only 25% or 75% of old backups.

The modified script has been uploaded to my GitHub repository. Use tmcleanup_50percent.sh (available via the links above) to delete 50% of old backups:

# Delete 50% of backups older than three months (i.e., retain biweekly backups older than 90 days)  
$ sudo ./tmcleanup.sh /Volumes/Time Machine Backup/Backups.backupdb blanboom-studio 90  

# Run the script twice consecutively to delete 75% of backups older than one year (i.e., retain monthly backups older than 365 days)  
$ sudo ./tmcleanup.sh /Volumes/Time Machine Backup/Backups.backupdb blanboom-studio 365  
$ sudo ./tmcleanup.sh /Volumes/Time Machine Backup/Backups.backupdb blanboom-studio 365

Deep-Dive Analysis of Time Machine Disk Usage with BackupLoupe

The aforementioned scripts provide convenient ways to delete old backups—but to conduct deeper, targeted analysis of Time Machine’s disk usage, you’ll need BackupLoupe:

BackupLoupe offers two key capabilities:

  1. Identifying which backups consume the most disk space—enabling selective deletion of large backups.
  2. Analyzing which specific files and directories within backups occupy the most space—allowing you to selectively delete large, non-critical items (e.g., Steam game libraries, large apps, virtual machines, iOS simulators, video files).

By strategically removing such non-essential large files from backups, you free up space for Time Machine to store more historical versions of critical data (e.g., personal documents, photos), thus maximizing utilization of your backup storage.

Using BackupLoupe is straightforward: launch the app, let it build its index, and you’ll immediately see detailed space usage per backup and per directory inside each backup:


BackupLoupe displays disk usage for all historical backups

Note, however, that BackupLoupe itself provides only analysis—it does not include built-in cleanup functionality. For instructions on manually deleting specific files or directories from backups, refer to this guide:

Notes: