tmutil: command line interface into Time Machine

root's picture

Time Machine has been blessed with a nice command line interface called tmutil. By using it you can extend the Time Machine features because not everything can be done from common graphical interface.
Below I will show you some examples.

Starting with the investigation: if you find yourself having backup failing without too much information, fire up the terminal and start the following command.

log stream --info --style compact --predicate 'subsystem=="com.apple.TimeMachine"'

How to List backups:

fmbp:~ florian$ tmutil listbackups
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-05-13-180011
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-05-29-181521
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-06-13-200228
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-07-09-021324
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-07-20-170655
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-08-03-095215

How to display the latest backup:

fmbp:~ florian$ tmutil latestbackup
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-08-03-095215

How to see the Time Machine backup destination:

fmbp:~ florian$ tmutil destinationinfo
Destination type: Network
Destination info: afp://florian@192.169.69.9/FlorianData

How to check the backup status:

fmbp:~ florian$ tmutil status
Backup session status:
{
    BackupPhase = HealthCheckCopyHFSMeta;
    ClientID = "com.apple.backupd";
    DateOfStateChange = "2012-08-03 08:54:14 +0000";
    Percent = "0.07999999821186066";
    Running = 1;
    Stopping = 0;
}
fmbp:~ florian$ tmutil currentphase
HealthCheckCopyHFSMeta

How to disable the local snapshots:

fmbp:~ root# tmutil disablelocal

How to stop a running backup:

fmbp:~ root# tmutil stopbackup
fmbp:~ root# tmutil status
Backup session status:
{
    BackupPhase = CalculatingChanges;
    ClientID = "com.apple.backupd";
    DateOfStateChange = "2012-08-03 09:28:53 +0000";
    DestinationMountPoint = "/Volumes/Time Machine Backups";
    NumberOfChangedItems = 27165;
    Percent = 0;
    Running = 1;
    [color=red]Stopping = 1;[/color]
}

How to disable the backup and check the Time Machine status:

fmbp:~ root# tmutil disable

...after a minute or two:

fmbp:~ root# tmutil status
Backup session status:
{
    ClientID = "com.apple.backupd";
    DestinationMountPoint = "/Volumes/Time Machine Backups";
    Percent = 1;
    Running = 0;
}

How to enable the backup:

fmbp:~ root# tmutil enable

How to start the backup and check the Time Machine status:

fmbp:~ root# tmutil startbackup
fmbp:~ root# tmutil status
Backup session status:
{
    BackupPhase = MountingBackupVol;
    ClientID = "com.apple.backupd";
    DateOfStateChange = "2012-08-03 09:35:48 +0000";
    DestinationMountPoint = "/Volumes/Time Machine Backups";
    Percent = "-1";
    Running = 1;
    Stopping = 0;
}

How to delete backups from Time Machine in HFS+:

NOTE: this feature does not work on macos Big Sur and up. Check the next example.

fmbp:~ root# tmutil listbackups
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-05-13-180011
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-05-29-181521
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-06-13-200228
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-07-09-021324
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-07-20-170655
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-08-03-095215
fmbp:~ root# tmutil delete "/Volumes/Time Machine Backups/Backups.backupdb/FM\342\200\231s MacBook Pro/2012-05-29-181521"
fmbp:~ root# tmutil delete "/Volumes/Time Machine Backups/Backups.backupdb/FM\342\200\231s MacBook Pro/2012-07-09-021324"
fmbp:~ root# tmutil delete "/Volumes/Time Machine Backups/Backups.backupdb/FM\342\200\231s MacBook Pro/2012-06-13-200228"
fmbp:~ root# tmutil listbackups
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-05-13-180011
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-07-20-170655
/Volumes/Time Machine Backups/Backups.backupdb/FM's MacBook Pro/2012-08-03-095215

How to delete backups from Time Machine in APFS:

NOTE: this feature works only on APFS filesystem. Check the previous example for HFS+.

myarm:TM root# tmutil listbackups
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-101215.backup/2024-10-29-101215.backup
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-111159.backup/2024-10-29-111159.backup
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-121229.backup/2024-10-29-121229.backup
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-131243.backup/2024-10-29-131243.backup
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-141230.backup/2024-10-29-141230.backup
myarm:TM root# tmutil delete -d /Volumes/DATA -t 2024-10-29-101215
1 backups deleted
myarm:TM root# tmutil delete -d /Volumes/DATA -t 2024-10-29-111159
1 backups deleted
myarm:TM root# tmutil delete -d /Volumes/DATA -t 2024-10-29-121229
1 backups deleted
myarm:TM root# tmutil delete -d /Volumes/DATA -t 2024-10-29-131243
1 backups deleted
myarm:TM root# tmutil listbackups
/Volumes/.timemachine/2516975E-A2B9-47F0-A943-65C1BB0FB642/2024-10-29-141230.backup/2024-10-29-141230.backup

How to compare backups:

The output below is truncated. It will normally show all differences but it was trimmed only to show you some usual outputs of modifications (time, size, deletion, addition). At the end, will show full size differences.

fmbpro:~ florian$ tmutil compare "/Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-162537" "/Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850"
[...]
!         (mtime)               /Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850/Florian/Users/florian/Desktop
+ 3.6M                          /Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850/Florian/Users/florian/Desktop/FILE_ADDED.TXT
- 4.2M                          /Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850/Florian/Users/florian/Desktop/FILE_DELETED.TXT
! 16.0M   (mtime)         /Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850/Florian/Users/florian/Desktop/FILE_DATE_MODIFIED.TXT
! 356B    (size, mtime)   /Volumes/Time Machine Backups/Backups.backupdb/fmbpro/2020-03-22-182850/Florian/Users/florian/Desktop/FILE_SIZE_MODIFIED.TXT
[...]
-------------------------------------
Added:         78.8M
Removed:       39.2M
Changed:       3.8G
fmbpro:~ florian$

Thou shalt not steal!

If you want to use this information on your own website, please remember: by doing copy/paste entirely it is always stealing and you should be ashamed of yourself! Have at least the decency to create your own text and comments and run the commands on your own servers and provide your output, not what I did!

Or at least link back to this website.

Recent content

root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root
root