Restore Time Machine backup from Terminal

Sometimes you need to quickly restore a file from your macOS Time Machine backups without using the pretty graphical interface.

1. Catalina note
2. Commands

Catalina note

Since macOS 10.5 you could be asked permission to allow Terminal access to the intended folders. This is okay, but you may wish to revoke access for the Terminal app when you are done. You can do this in System Preferences > Security and Privacy > Privacy > Files and folders and/or Full disk access.

Commands

First retrieve the list of all available backups:

tmutil listbackups

When you get an error “No machine directory found for host” it probably means Time Machine is doing a backup or verification at the moment. Try again later.

You can check the status and get an ETA with:

tmutil status

Restore your file:

tmutil restore '$BACKUP_PATH/$ORIGINAL_PATH' '$DESTINATION'

Note: don’t forget to either wrap the paths in quotes or escape all spaces and special characters!

$BACKUP_PATH

/Volumes/Time Machine Backups/Backups.backupdb/ComputerName/2017-10-19-064032

The starting path can be different for non-English installations. For example on Dutch macOS the path can start with /Volumes/Time Machine-reservekopiën.

$ORIGINAL_PATH

/Macintosh HD/Users/username/Documents/my_lost.doc

Here the start ‘Macintosh HD’ can also be different depending on the name of your disk.

$DESTINATION

~/Documents/my_lost.doc

So the full restore command becomes like:

tmutil restore '/Volumes/Time Machine Backups/Backups.backupdb/ComputerName/2017-10-19-064032/Macintosh HD/Users/username/Documents/my_lost.doc' '~/Documents/my_lost.doc'

Based on: Hacks for Macs

Changelog
2019-12-27 – Added macOS Cataline note