Time Machine utility

tmutil verb [options]

Control and interact with Time Machine, as well as examining and manipulating backups, including restoring data from backups, editing exclusions, and comparing backups.


verbs shown in brown require root privledge.
latestbackup displays the path to the most recent snapshot for this computer.
tmutil latestbackup
listbackups displays paths for all of this computer's completed snapshots.
 tmutil listbackups
machinedirectory Displays the path to the current machine directory for this computer.
tmutil machinedirectory
Turn on/off automatic backups.
Turn on local Time Machine snapshots.
Turn off local Time Machine snapshots and trigger automatic cleanup of accumulated local snapshot data.
restore [-v] src …   dst Restore src, inside a snapshot, to dst.
The dst argument uses the destination path semantics of cp.

When using restore, tmutil behaves like Finder.
Custom Time Machine metadata (extended security and other) will be removed from the restored data, and other metadata will be preserved.

Root privileges may be required to perform restores depending on dst.
cp or ditto.
When restoring as root, ownership of the restored items will match the state of the items in the backup.

snapshot Create new local Time Machine snapshot.
startbackup [-b | --block] equivalent to choosing "Back Up Now" from the Time Machine menu extra.
--block wait (block) until the backup is finished before exiting.
stopbackup Cancel a backup currently in progress.
addexclusion item … file, directory

location-independent exclusion(sticky) :
        Moved item is still excluded.
        Copy of item retains the exclusion.

addexclusion -p path … fixed-path exclusion:
Files within the path at the time of the backup are excluded.

Volume exclusions are implicitly fixed-path exclusions and are retained if the volume name or mount path changes.
Erasing the volume clears it's exclusions. (See associatedisk.)

removeexclusion [-p] item
isexcluded item … Determine if a file, directory, or volume are excluded from Time Machine backups.
tmutil isexcluded /Applications/
[Included]    /Applications/

tmutil isexcluded /Volumes/OtherSysSaves/kitchen
[Excluded]    /Volumes/OtherSysSaves/kitchen
delete snapshot_path … in an arbitrary machine directory.
Can delete snapshots from backups that were not made by, or are not claimed by, the current machine.
calculatedrift machine_directory Analyze the snapshots in a machine directory and determine the amount of change between each.
Averages are displayed after all snapshots have been analyzed.
Root privileges may be required, depending on the contents of the machine directory.
 tmutil calculatedrift /Volumes/bakvol/Backups.backupdb/mymac

2011-07-04-120352 - 2011-08-12-201512
Added:         2.2G
Removed:       32.5G
Changed:       969.8M

2011-08-12-201512 - 2011-08-13-000030
Added:         78.9K
Removed:       0B
Changed:       256.4K


2011-08-25-200021 - 2011-08-25-210025
Added:         1.7M
Removed:       0B
Changed:       79.1M

Drift Averages
Added:         1.8G
Removed:       3.2G
Changed:       157.9M
uniquesize path ... Analyze the specified path and determine its unique size.
Things that only exist in the specified path; things that are hard-linked in other places are not tallied.
tmutil uniquesize /Volumes/DGerman1a/Backups.backupdb/smackerPro/0 
compare [-@esmugtdrEX]
[-D depth] [-I name]
snapshot_path |
 path1 path2]
create a diff listing

full example

  • No arguments: compare the computer to the latest snapshot.
  • One snapshot path: compare the computer to the specified snapshot.
  • Two path: compare two snapshots .

    Default property set: -smugt .

    compare vary operation
    -a all supported metadata -D limit traversal depth to depth levels from the beginning of iteration
    -@ extended attributes -I Ignore paths with a path component equal to name during iteration. May be specified multiple times
    -e ACLs
    -s sizes -X output in XML property list format
    -m file modes -E don't take exclusions into account when comparing items inside volumes
    -u UIDs
    -g GIDs -r ignore specified root paths and compare descendents instead
    -t modification times
    -d file data forks -v verbose depricated
  • setdestination [-p] argConfigure a local HFS+ volume or AFP share as the backup destination.

    To set an HFS+ volume as the backup destination, arg is the mount point of the volume.
    When setting an AFP destination arg takes the form: afp://user[:pass]@host/share

    -p password interactive prompt.

    inheritbackup {machine_directory |
    Claim a machine directory or sparsebundle for use by the current machine.

    Machine directories and sparsebundles are owned by one computer at a time,
    and are tracked by unique identifiers. inheritbackup reassigns the identity of the specified item, reconfiguring it so the current host recognizes it during backups.
    When inheriting a sparsebundle, the machine directory within will also be claimed.

    Inheriting is typically only one step in the process of configuring a backup for use by a machine.
    See setdestination and/or associatedisk

    One machine can own multiple machine directories and sparsebundles , but it is ill-advised for them to reside in the same place.

    inheritbackup attempts to detect identity collisions before making changes.

    1/1/13, The backup "oldMachine" can't be inherited because it would conflict with "machine 3".

    associatedisk [-a] mount_point          snapshot_volume Bind a snapshot volume directory to the specified local disk and configure the backup history.

    Time Machine uses the HFS+ volume persistent UUID assigned when the file system was created to associate a source volume and a snapshot volume.

    Erasing a volume creates a new file system on the disk and previous assocation to a time machine snapshot is broken.
    After restoring a volume's contents, use associatedisk to have Time Machine consider the volume backed up.

    sudo tmutil associatedisk -a /Volumes/MyNewStuffDisk

    -a all snapshot volumes in the same machine directory that match the MyStuff will be associated .

    help [verb] Display usage for a verb.

    tmutil without verb reports:

    Usage: tmutil help  
    Usage: tmutil version 
    Usage: tmutil enable 
    Usage: tmutil disable 
    Usage: tmutil startbackup [-b | --block] [-r | --rotation] [-d | --destination dest_id] 
    Usage: tmutil stopbackup 
    Usage: tmutil enablelocal 
    Usage: tmutil disablelocal 
    Usage: tmutil snapshot 
    Usage: tmutil delete snapshot_path ...  
    Usage: tmutil restore [-v] src dst 
    Usage: tmutil compare [-a@esmugtdEX] [-D depth] [-I name]
           tmutil compare [-a@esmugtdEX] [-D depth] [-I name] snapshot_path
           tmutil compare [-a@esmugtdEX] [-D depth] [-I name] path1 path2
    Usage: tmutil setdestination [-a]  mount_point
           tmutil setdestination [-ap] afp://user[:pass]@host/share 
    Usage: tmutil removedestination destination_id 
    Usage: tmutil destinationinfo [-X] 
    Usage: tmutil addexclusion [-p] item ...  
    Usage: tmutil removeexclusion [-p] item ...  
    Usage: tmutil isexcluded item ...  
    Usage: tmutil inheritbackup machine_directory
           tmutil inheritbackup sparse_bundle 
    Usage: tmutil associatedisk [-a] mount_point volume_backup_directory 
    Usage: tmutil latestbackup 
    Usage: tmutil listbackups 
    Usage: tmutil machinedirectory 
    Usage: tmutil calculatedrift machine_directory 
    Usage: tmutil uniquesize path ...  
    Use `tmutil help ` for more information about a specific verb.

    Backup Structures

    "realms" associated with Time Machine backups, definitions:  
    backup source volume currently being backed up by Time Machine.
    backup disk HFS+ volume that contains Time Machine backups.
    backup destination In the case of a local destination, a synonym for backup disk.
    For network destinations, this is the AFP share on which the backup disk image resides.
    backup disk image
    backup image
    sparsebundle that, when mounted, is the backing store for a volume that is a backup disk.
    backup store top-level Backups.backupdb directory at the root of a backup disk.
    machine directorydirectory inside a backup store that contains all the backups for a particular computer.
    For local destinations, a backup store can contain multiple machine directories, all for separate computers.
    snapshotdirectory inside a machine directory that represents a single initial or incremental backup of one computer.
    "snapshot", in most contexts, is a generic term and is not to be confused with a "local Time Machine snapshot", which is simply a snapshot stored locally on the computer.
    snapshot volumedirectory inside a snapshot that represents a single initial or incremental backup of one backup source. Example:
    /Volumes/Chronoton/Backups.backupdb/thermopylae/2011-07-03-123456/Mac HD


    <key>Label</key> <string></string>
        <array> <string>/System/Library/CoreServices/backupd.bundle/
                                         Contents/Resources/</string> </array>
        <key>StartOnMount</key> <true/>
     <key>Disabled</key> <true/>
        <key>EnableTransactions</key> <false/>
        <key>KeepAlive</key> <true/>
        <key>Label</key> <string></string>
        <key>MachServices</key> <dict> <key></key> <true/> </dict>
        <key>RunAtLoad</key> <true/> 
    <key>Label</key> <string></string>
            <key></key> <true/>
            <key></key> <dict> 
            <key>HideUntilCheckIn</key> <true/> </dict>
        <key>ProgramArguments</key> <array> <string>/System/Library/CoreServices/backupd.bundle/Contents/Resources/mtmd</string> </array>
        <key>KeepAlive</key> <dict> <key>Crashed</key> <true/> </dict>
        <key>POSIXSpawnType</key> <string>Interactive</string>
        <key>EnvironmentVariables</key> <dict>
            <!--Uncomment to enable various debugging options-->
            <!--<key>WaitForDebugger</key>--> <!--<true/>-->
            <!--<key>MallocScribble</key>--> <!--<string>1</string>-->
            <!--<key>MallocStackLogging</key>--> <!--<string>1</string>--> </dict>
        <key>CFBundleIdentifier</key> <string></string>

    TimeMachine writes messages like these to system.log and syslog with level = notice

    Feb 14 17:44:10 smackerpro[14355]: Copied 702 items (22.1 MB) from volume DATA. Linked 45215.
    Feb 14 17:44:24 smackerpro[14355]: Copied 2 items (14 bytes) from volume Photos. Linked 93.
    Feb 14 17:44:31 smackerpro[14355]: Copied 56 items (7.1 MB) from volume Macintosh HD. Linked 652.
    Feb 14 17:44:34 smackerpro[14355]: Created new backup: 2016-02-14-174434
    Feb 14 17:44:36 smackerpro[14355]: Starting post-backup thinning
    Feb 14 17:44:36 smackerpro[14355]: No post-backup thinning needed: no expired backups exist
    Feb 14 17:44:36 smackerpro[14355]: Backup completed successfully.
    defaults read /Library/Preferences/ Destinations edited
     defaults read /Library/Preferences/
        AlwaysShowDeletedBackupsWarning = 1;
        AutoBackup = 1;
            BackupAlias = <0 01260002 00010944 4765726d 616e3161 0 0 0 0 0000c8ac 6c1f482b 0 00010944 4765726d 616e3161 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0002c8ac 6c1f0000 0 0000ffff ffff0000 09000000 0 0 0 00094447 65726d61 6e316100 00100008 0000c8ac a45f0000 00110008 0000c8ac a45f0000 00010000 00020013 44476572 6d616e31 613a4447 65726d61 6e316100 000e0014 00090044 00470065 0072006d 0061006e 00310061 000f0014 00090044 00470065 0072006d 0061006e 00310061 00120000 00130012 2f566f6c 756d6573 2f444765 726d616e 3161ffff 0000>;
            DateOfLatestWarning = "2019-06-25 16:24:45 +0000";
            DestinationID      = "AE9B1E0A-A1F1-408B-8118-E572456F0372";
            DestinationUUIDs = ( "B2BA3CA8-984F-39F5-8A16-261BCBC2CE28");
            LastKnownEncryptionState = NotEncrypted; RESULT = 18;
            RootVolumeUUID = "D12613A2-FB47-3DF4-8035-9DB9DD6E5E01";
            SnapshotDates =         (
                "2016-02-14 20:49:45 +0000", "2016-02-26 00:00:38 +0000", "2016-03-05 21:17:04 +0000",
                "2017-03-26 16:13:42 +0000", "2017-04-16 01:52:10 +0000", "2017-04-16 02:36:05 +0000");
            BackupAlias = <0 016e0002 00011273 6d616370 726f5469 6d654d61 6368696e 65000000 0 0000d571 c23a482b 0 00011273 6d616370 726f5469 6d654d61 6368696e 65000000 0 0 0 0 0 0 0 0 0 0 0 0002d571 c23a0000 0 0000ffff ffff0000 09000000 0 0 0 0012736d 61637072 6f54696d 654d6163 68696e65 00100008 0000d571 fa7a0000 00110008 0000d571 fa7a0000 00010000 00020025 736d6163 70726f54 696d654d 61636869 6e653a73 6d616370 726f5469 6d654d61 6368696e 6500000e 00260012 0073006d 00610063 00700072 006f0054 0069006d 0065004d 00610063 00680069 006e0065 000f0026 00120073 006d0061 00630070 0072006f 00540069 006d0065 004d0061 00630068 0069006e 00650012 00000013 001b2f56 6f6c756d 65732f73 6d616370 726f5469 6d654d61 6368696e 6500ffff 0000>;
            BytesAvailable = 297727688704; BytesUsed = 368677650432;
            DestinationID      = "014FFD4C-0482-4517-9570-812CBF7FBAB3";
            DestinationUUIDs = ( "6AC7B43D-0761-3820-8CB5-D8E59169F4EF");
            LastKnownEncryptionState = NotEncrypted;
            RESULT = 100;
            RootVolumeUUID = "D12613A2-FB47-3DF4-8035-9DB9DD6E5E01";
        ExcludeByPath =     ( "/Users/Shared/adi");
        HostUUIDs =     ( "9205DB27-ADBE-5C67-B58F-AE743BF777D9");
        LastConfigurationTraceDate = "2018-07-21 19:03:31 +0000";
        LastDestinationID = "014FFD4C-0482-4517-9570-812CBF7FBAB3";
        LocalizedDiskImageVolumeName = "Time Machine Backups";
        MobileBackups = 1;
        PreferencesVersion = 4;
        RequiresACPower = 0;
        SkipSystemFiles = 0;


    Unable to locate machine directory for host.

    sudo defaults write /System/Library/Launch Daemons/ StartInterval -int 1800

    COmmand+Shift+G opens GoToFolder dropdown. see /privat/etc