Skip to content

deucalion restore

Copies files or folders from the backup back to your computer: to where they were, or into another folder. It always shows a plan first and asks before changing anything. Anything it replaces is kept in the undo folder ~/Deucalion-before-restore/.

$ deucalion restore --help
usage: deucalion restore [-h] [--to DIR] [--dry-run] [--details] [-y] [--target NAME]
                         PATH [PATH ...]

restore files or folders from the backup

positional arguments:
  PATH           e.g. ~/Documents/report.pdf

options:
  -h, --help     show this help message and exit
  --to DIR       restore into this folder instead of the original place
  --dry-run      show what would happen, change nothing
  --details      list every file that would be overwritten
  -y, --yes      don't ask for confirmation
  --target NAME  which registered drive to use
Option What it does
PATH … What to restore: one or more files or folders, as paths on your computer (~/Documents/report.pdf) or in the backup (home/Documents). A folder includes everything inside it.
--to DIR Restore into this folder instead: each item is restored inside DIR with its own name (--to ~/Desktop/Recovered puts ~/Documents/Work in ~/Desktop/Recovered/Work). Nothing in the original place is touched.
--dry-run Show the plan and change nothing.
--details List every file that would be replaced (normally the first 15).
-y, --yes Don't ask Restore now?
--target NAME Which backup drive.

Example

$ deucalion restore "~/Documents/Budget 2026.ods"
Restore plan
  home/Documents/Budget 2026.ods  →  /home/alex/Documents/Budget 2026.ods
  New:                     0
  Overwrite:               1   (current versions are moved aside first)
  Already the same:        0
  To copy:                 1   44.9 KB
  Will overwrite:
    /home/alex/Documents/Budget 2026.ods
Restore now? [y/N] y
Restored 1 file (44.9 KB).
Files that were replaced are kept in /home/alex/Deucalion-before-restore/2026-10-12_091135

The plan shows:

Line Meaning
… → … Each item and where it goes.
New Files and folders that don't exist there now.
Overwrite Items that exist there and are different. They are moved aside to the undo folder first (renamed, never copied and deleted).
Already the same Identical already (same size, date and content); not copied.
To copy Number and size of files to copy.
Missing on drive In the manifest, but missing on the drive (for example after a drive problem). They can't be restored; the others are.
Will overwrite The files that will be replaced.

Into another folder:

$ deucalion restore ~/Documents/Work --to ~/Desktop/Recovered
Restore plan
  home/Documents/Work  →  /home/alex/Desktop/Recovered/Work
  New:                     3
  Overwrite:               0   (current versions are moved aside first)
  Already the same:        0
  To copy:                 2   93.8 KB
Restore now? [y/N] y
Restored 2 files (93.8 KB).

Restoring for a different user name

Your home folder in the backup is restored into your current home folder, whatever its path. A backup made as /home/alex restores into /home/alexk if that is your home folder now. (A rebuild also updates paths inside settings files.)

The system recipe

The system/ part can't be restored in place. Restore it into a folder to read it:

$ deucalion restore system/desktop --to ~/Desktop/recipe
Restore plan
  system/desktop  →  /home/alex/Desktop/recipe/desktop
  New:                     2
  Overwrite:               0   (current versions are moved aside first)
  Already the same:        0
  To copy:                 1   172 B
Restore now? [y/N] y
Restored 1 file (172 B).

Without --to, it goes to a deucalion-system folder in the current folder.

Messages

Message Meaning
… is not part of the backup. / … is not in the backup. The path isn't in the backup (check with ls).
“…” and “…” would be restored to the same place (…). Restore them separately, or into different folders. Two items with the same name with --to.
Nothing to restore: everything is already the same. Nothing to do.
… : not restored (…); the version that was there has been kept (see above). A file couldn't be restored; your version is safe.
… : restored, but its content does not match the checksum recorded at backup time. The copy on the drive may be damaged. Check the drive with verify --full.

Exit codes

0 restored (or nothing to do, or --dry-run); 1 an error, or you answered no ("Nothing was changed."); 130 stopped (what was restored stays; a file being replaced is put back).