You broke the system after an upgrade
You run a major dnf upgrade on a Friday afternoon. Monday morning, your desktop environment refuses to start, or a critical service hangs on boot. You need to roll back to a known-good state without reinstalling the OS or manually hunting down which package broke the system. That is exactly why Fedora defaults to Btrfs. The filesystem already supports instant snapshots. You just need a tool to manage them. Timeshift fills that gap.
What is actually happening
Btrfs does not copy your entire disk when you take a snapshot. It uses copy-on-write. When you create a snapshot, the filesystem records the current state of the directory tree. As you modify files afterward, Btrfs allocates new blocks for the changes and leaves the old blocks untouched. The snapshot points to those original blocks. Reverting is just a matter of swapping the active subvolume pointer back to the snapshot subvolume. The operation takes seconds, not hours.
Timeshift automates this process. It creates a dedicated subvolume for storing snapshots, handles the naming convention, and provides a simple interface to list, mount, and revert to previous states. Without it, you would need to remember btrfs subvolume snapshot syntax and manually track which snapshot corresponds to which system state. Timeshift removes the guesswork.
The tool also handles the administrative overhead. It prunes old snapshots based on retention policies, labels each restore point with a timestamp and a custom comment, and integrates with systemd timers for scheduled backups. You get a reliable safety net without maintaining a custom bash script.
Run journalctl first. Read the actual error before guessing.
The fix
Install the package from the default Fedora repositories. The package pulls in the necessary dependencies and sets up the systemd timer for automated backups.
sudo dnf install timeshift -y
# --refresh ensures you get the latest metadata before installing
# -y skips the confirmation prompt for a clean install
# dnf upgrade --refresh is your normal weekly maintenance command
Run the configuration wizard. Timeshift defaults to RSYNC mode, which copies files to a separate partition. You must explicitly select Btrfs mode to leverage the native filesystem features.
sudo timeshift --init --btrfs
# --init launches the interactive setup wizard
# --btrfs forces the tool to use native Btrfs snapshots instead of RSYNC
# The wizard will prompt for the device path and snapshot subvolume name
The wizard will ask for the device path. Select the root partition where Fedora is installed. It will then ask for the subvolume name for the snapshots. The default @timeshift is fine. Accept the defaults unless you have a custom Btrfs layout. The wizard finishes by creating the snapshot subvolume and setting up the initial configuration file in /etc/timeshift/timeshift.json.
Create your first manual snapshot immediately. This establishes a baseline before you make any system changes.
sudo timeshift --create --comments "Pre-upgrade baseline"
# --create triggers the snapshot process
# --comments attaches a human-readable label for later identification
# Always label snapshots with the action you are about to perform
Enable automated snapshots. Timeshift ships with a systemd timer that runs daily. Verify it is active and masked correctly.
sudo systemctl enable --now timeshift-autosnap.service
# Enables the service to run on boot and starts it immediately
# The timer is handled by timeshift-autosnap.timer, which triggers this service
# systemctl status timeshift-autosnap.timer shows the next scheduled run
Check the timer schedule to confirm it aligns with your maintenance window.
systemctl list-timers --all | grep timeshift
# Shows the next scheduled run and the last trigger time
# Confirms the automation is actually queued in systemd
# journalctl -xe reads better than journalctl alone for debugging timers
Snapshot the system before the upgrade. Future-you will thank you.
Verify it worked
List the available snapshots to confirm Timeshift recorded the baseline correctly.
sudo timeshift --list
# Displays a table of snapshot IDs, dates, and comments
# Verify the ID matches the comment you just provided
# The output shows snapshot type, device, and disk space used
Inspect the Btrfs subvolume structure directly. This confirms Timeshift created the correct directory hierarchy and did not fall back to a file-based backup.
sudo btrfs subvolume list / | grep timeshift
# Shows the snapshot subvolumes under the @timeshift directory
# Each line represents a read-only snapshot with a unique generation ID
# The ro flag confirms Btrfs is treating them as immutable snapshots
If you see a list of subvolumes with the ro flag, the native Btrfs integration is working. The snapshots are space-efficient and instant.
Mount a snapshot read-only to verify your files are intact before committing to a rollback.
sudo mount -o ro,subvol=@timeshift/2024-01-15_14-30-00 /dev/nvme0n1p3 /mnt/verify
# Mounts the specific snapshot to a temporary directory
# The ro flag prevents accidental writes to the snapshot
# Replace the device and snapshot ID with your actual values
Browse /mnt/verify to confirm your configuration files and user data match the expected state. Unmount it when you are done.
sudo umount /mnt/verify
# Cleans up the temporary mount point
# Always unmount snapshots after inspection to avoid stale references
# systemd automount units handle this automatically in production
Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and what the error looks like
The most frequent mistake is skipping the --btrfs flag during initialization. Timeshift will silently default to RSYNC mode. You will see a warning during the first snapshot attempt.
WARNING: RSYNC mode selected. This will copy files to a separate partition.
Btrfs mode is recommended for systems using the Btrfs filesystem.
If you see this, stop. Run sudo timeshift --init --btrfs again. RSYNC mode defeats the purpose of using Btrfs. It consumes extra disk space and takes minutes instead of seconds.
Another common issue involves custom Btrfs layouts. If you manually created a @home subvolume and mounted it separately, Timeshift might fail to include it in the snapshot. The tool expects a standard Fedora layout. If your /home lives on a separate subvolume, you must add it to the Timeshift configuration manually.
Edit the configuration file. Never edit files in /usr/lib/. Always modify copies in /etc/.
sudo nano /etc/timeshift/timeshift.json
# Open the main configuration file for manual edits
# Timeshift stores all persistent settings here
# Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package.
Locate the include array and add your custom subvolume path. Save the file and run a test snapshot. If the path is incorrect, Timeshift will abort with a clear filesystem error.
ERROR: Failed to create snapshot. Subvolume /home does not exist or is not a Btrfs subvolume.
SELinux denials can also interrupt the process if you have modified the default contexts. Check the audit log before disabling security policies.
sudo journalctl -t setroubleshoot | tail -n 20
# Filters SELinux denial messages from the journal
# Shows the exact process and file causing the context mismatch
# SELinux denials show up here with a one-line summary. Read those before disabling SELinux.
Disk space exhaustion is the silent killer. Btrfs snapshots share blocks until they diverge. If you fill the filesystem, new snapshots will fail. Monitor usage regularly.
btrfs filesystem usage /
# Displays total disk space, allocated space, and unallocated space
# The Data and Metadata sections show how much space snapshots are consuming
# Plan upgrades on the 6-month Fedora release cadence to avoid sudden space spikes
If the boot menu is gone, GRUB rescue is your friend, not your enemy.
When to use this vs alternatives
Use Timeshift when you want a straightforward, point-and-click style tool that handles Btrfs snapshots without requiring deep filesystem knowledge. Use snapper when you need granular, per-package rollback capabilities and want to integrate directly with dnf transaction logs. Use raw btrfs subvolume snapshot commands when you are writing custom automation scripts and need precise control over subvolume naming and mount points. Use steward when you prefer a lightweight, terminal-native wrapper that focuses exclusively on Btrfs without GUI dependencies. Stay on Timeshift if you only deviate from the defaults occasionally and want a reliable safety net for major system changes.