The Complete
Snapper Guide

What is Snapper and why should you care?

A snapshot is a frozen copy of your filesystem at a specific point in time. On openSUSE, the root partition uses Btrfs (B-tree filesystem) by default, which supports snapshots natively. Snapper is the tool that manages those snapshots.

Here's why this matters: every time you run zypper dup or install a package, Snapper automatically creates two snapshots — a "pre" snapshot (before the change) and a "post" snapshot (after the change). If the update breaks something, you can roll back to the pre-snapshot. Your system is restored exactly as it was. The whole process takes under two minutes.

Snapshot Types

Type	When	Purpose
Pre	Before a zypper/Myrlyn operation	Captures the "before" state
Post	After a zypper/Myrlyn operation	Captures the "after" state. Linked to its pre-snapshot.
Single	Manual, or timeline-based	Standalone snapshot — no pre/post pair

Check if Snapper is set up Beginner

If you installed openSUSE with the default Btrfs partitioning, Snapper is already configured and working. Let's verify:

# Check Snapper configurations
sudo snapper list-configs

You should see output like:

Config  | Subvolume
--------+----------
root    | /

This means Snapper is configured for the root filesystem. Now check that snapshots exist:

# List all snapshots
sudo snapper list

You should see a list of pre/post pairs from your zypper operations. If you see snapshots — you're all set. Snapper has been working in the background since you installed.

What if Snapper isn't set up?

If snapper list-configs shows nothing, you either didn't install with Btrfs, or something went wrong. To set it up manually:

# Verify your root is Btrfs
df -T / | grep btrfs

# If it is, create the default root config
sudo snapper -c root create-config /

# Verify
sudo snapper list-configs

Listing snapshots Beginner

# List all snapshots
sudo snapper list

# Example output:
#  # | Type   | Pre # | Date                     | User | Cleanup  | Description           | Userdata
# ---+--------+-------+--------------------------+------+----------+-----------------------+---------
#  0 | single |       |                          | root |          | current               |
#  1 | pre    |       | Mon 01 Apr 2026 14:22:01 | root | number   | zypper dup            |
#  2 | post   |     1 | Mon 01 Apr 2026 14:25:33 | root | number   | zypper dup            |
#  3 | pre    |       | Wed 03 Apr 2026 09:11:00 | root | number   | zypper install firefox|
#  4 | post   |     3 | Wed 03 Apr 2026 09:11:15 | root | number   | zypper install firefox|
#  5 | single |       | Thu 04 Apr 2026 10:00:00 | root |          | Manual snapshot       |

Key things to understand:

• Snapshot 0 is always "current" — your running system
• Pre/Post pairs are linked — snapshot 2's "Pre #" column shows 1, meaning it's the post to snapshot 1's pre
• Cleanup column shows how the snapshot will be managed — "number" means it follows the number-based retention policy
• Description tells you what triggered the snapshot

# List with more detail (shows space used)
sudo snapper list -a

# List only snapshots from a specific type
sudo snapper list --type pre-post
sudo snapper list --type single

Creating manual snapshots Beginner

Automatic snapshots cover zypper and Myrlyn operations. But you should create manual snapshots before doing anything risky — editing config files, installing from a third-party repo, running scripts, etc.

Single Snapshot

# Create a simple snapshot
sudo snapper create --description "Before editing GRUB config"

# Verify it was created
sudo snapper list

Pre/Post Pair (Manual)

You can create your own pre/post pairs around any operation:

# Create the pre-snapshot (note the number it returns)
sudo snapper create --type pre --description "Before risky script"
# Output: 10

# Do your risky thing here...
sudo ./risky-script.sh

# Create the post-snapshot, linking to the pre
sudo snapper create --type post --pre-number 10 --description "After risky script"

One-liner with snapper create

# Run a command wrapped in automatic pre/post snapshots
sudo snapper create --command "zypper install something-experimental"

Seeing what changed Intermediate

One of Snapper's most useful features — you can see exactly what files changed between any two snapshots.

# See which files changed between snapshots 1 and 2
sudo snapper status 1..2

# Output shows:
# +..... /etc/zypp/repos.d/new-repo.repo    (+ = created)
# c..... /etc/ld.so.cache                    (c = content changed)
# -..... /usr/bin/old-binary                 (- = deleted)

# View the actual diff of a specific file
sudo snapper diff 1..2 /etc/fstab

# Compare current system (0) with a snapshot
sudo snapper status 5..0

# Show all diffs (can be long!)
sudo snapper diff 1..2

Symbol	Meaning
+	File was created (exists in the newer snapshot but not the older)
-	File was deleted
c	Content changed
t	Type changed (e.g. file → symlink)
p	Permissions changed
u	User ownership changed
g	Group ownership changed

Undoing changes (without rebooting) Intermediate

This is the targeted approach — revert specific changes without doing a full system rollback. Useful when you know exactly what went wrong.

# Undo ALL changes between snapshots 1 and 2
sudo snapper undochange 1..2

# Undo changes to a specific file only
sudo snapper undochange 1..2 /etc/fstab

# Undo changes but exclude certain files
sudo snapper undochange 1..2 --exclude /var/log

Restoring a single file from a snapshot

Every snapshot is accessible as a directory. You can browse and copy files from any snapshot:

# Snapshots live here
ls /.snapshots/

# Browse a specific snapshot's filesystem
ls /.snapshots/5/snapshot/etc/

# Restore a single file manually
sudo cp /.snapshots/5/snapshot/etc/fstab /etc/fstab

Full system rollback from GRUB Beginner

This is the nuclear option — and it's brilliant. If your system is so broken you can't even log in, you can recover from the GRUB boot menu.

Step-by-step rollback

Step 1: Reboot your machine

If you can still access a terminal, reboot normally: sudo reboot. If the system is frozen, hard reboot (hold the power button).

Step 2: At the GRUB menu, select "Start bootloader from a read-only snapshot"

This option appears in the GRUB boot menu by default on openSUSE. If you don't see GRUB (it boots too fast), hold Shift or press Esc during boot to make it appear.

Step 3: Choose your snapshot

GRUB shows a list of available snapshots with dates and descriptions. Pick the most recent one from before things broke — usually the latest "pre" snapshot.

Step 4: Verify the system works

The system boots into the snapshot in read-only mode. Check that everything works — desktop loads, apps open, internet connects. You're running from a frozen copy, so nothing you do here is permanent yet.

Step 5: Make the rollback permanent

# This makes the snapshot your new default system
sudo snapper rollback

# Reboot to complete
sudo reboot

After rebooting, your system is running from the rolled-back snapshot as the new default. The broken state is preserved as a snapshot too, so you haven't lost anything — you can always roll forward if needed.

Cleaning up snapshots Intermediate

Snapshots are space-efficient, but they're not free. Over time, if you have lots of changes, they accumulate. Snapper handles cleanup automatically, but you can manage it manually too.

# Check how much space Btrfs is using
sudo btrfs filesystem usage /

# List snapshots with space info
sudo snapper list -a

# Delete a specific snapshot
sudo snapper delete 15

# Delete a range
sudo snapper delete 10-25

# Delete all numbered snapshots older than a certain one
# (Snapper keeps a minimum based on your config)

# Run the automatic cleanup manually
sudo snapper cleanup number
sudo snapper cleanup timeline

# Check the cleanup timer
systemctl status snapper-cleanup.timer

Emergency: Disk full because of snapshots

# If you get "No space left on device" errors:

# 1. Delete old snapshots aggressively
sudo snapper delete 1-50

# 2. If still full, run a Btrfs balance
sudo btrfs balance start -dusage=5 /

# 3. Check usage again
sudo btrfs filesystem usage /

Configuring Snapper Advanced

Snapper's default settings work well for most people. But you can tune retention policies, space limits, and more.

# View current config
sudo snapper -c root get-config

Key settings

Setting	Default	What it does
NUMBER_LIMIT	4	Max number of regular numbered snapshots to keep
NUMBER_LIMIT_IMPORTANT	2	Max important numbered snapshots to keep
TIMELINE_CREATE	no	Whether to create hourly timeline snapshots
TIMELINE_LIMIT_DAILY	10	How many daily timeline snapshots to keep
FREE_LIMIT	0.2	Minimum free space (20%) before snapshots are cleaned
SPACE_LIMIT	0.2	Max space (20%) snapshots can use before cleanup
EMPTY_PRE_POST_CLEANUP	yes	Auto-delete pre/post pairs where nothing changed

# Change a setting
sudo snapper -c root set-config NUMBER_LIMIT=10
sudo snapper -c root set-config NUMBER_LIMIT_IMPORTANT=5

# Keep more snapshots if you have a large drive
sudo snapper -c root set-config NUMBER_LIMIT=20 NUMBER_LIMIT_IMPORTANT=10

# Or edit the config file directly
sudo nano /etc/snapper/configs/root

Snapshotting /home Advanced

By default, /home is NOT snapshotted. This is intentional — you don't want a system rollback to wipe your personal files. However, you can set up Snapper for /home if you want file versioning for your documents.

# Check if /home is Btrfs
df -T /home | grep btrfs

# If yes, create a Snapper config for home
sudo snapper -c home create-config /home

# Verify
sudo snapper list-configs
# Should show:
# Config  | Subvolume
# --------+----------
# root    | /
# home    | /home

# Create a manual snapshot of /home
sudo snapper -c home create --description "Before reorganising photos"

# List home snapshots
sudo snapper -c home list

# Compare changes in /home
sudo snapper -c home status 1..2

# Undo a change in /home
sudo snapper -c home undochange 1..2

For /home snapshots, consider enabling timeline snapshots so you get periodic snapshots even without package operations:

sudo snapper -c home set-config TIMELINE_CREATE=yes
sudo snapper -c home set-config TIMELINE_LIMIT_HOURLY=6
sudo snapper -c home set-config TIMELINE_LIMIT_DAILY=7
sudo snapper -c home set-config TIMELINE_LIMIT_WEEKLY=4

Timeline snapshots Advanced

By default, openSUSE only creates snapshots when you use zypper or Myrlyn. Timeline snapshots create periodic snapshots on a schedule, regardless of whether you've installed anything.

# Enable timeline snapshots for root
sudo snapper -c root set-config TIMELINE_CREATE=yes

# Configure retention
sudo snapper -c root set-config \
  TIMELINE_LIMIT_HOURLY=6 \
  TIMELINE_LIMIT_DAILY=7 \
  TIMELINE_LIMIT_WEEKLY=4 \
  TIMELINE_LIMIT_MONTHLY=6 \
  TIMELINE_LIMIT_YEARLY=1

# Enable the timer
sudo systemctl enable --now snapper-timeline.timer

# Check the timer is active
systemctl status snapper-timeline.timer

With this setup, Snapper creates a snapshot every hour. The cleanup algorithm then thins them out — keeping 6 hourly, 7 daily, 4 weekly, 6 monthly, and 1 yearly. This gives you a rich history to recover from.

Troubleshooting

"No space left on device" with lots of free space showing

Btrfs metadata can fill up even when data space is free. This is a known quirk:

# Check metadata usage specifically
sudo btrfs filesystem usage /
# Look at "Metadata" section — if "used" is close to "total", that's the problem

# Fix by rebalancing metadata
sudo btrfs balance start -musage=50 /

# Then clean old snapshots
sudo snapper delete 1-30

GRUB doesn't show snapshot boot option

# Regenerate GRUB config
sudo grub2-mkconfig -o /boot/grub2/grub.cfg

# Check that grub2-snapper-plugin is installed
rpm -q grub2-snapper-plugin

# If not:
sudo zypper install grub2-snapper-plugin
sudo grub2-mkconfig -o /boot/grub2/grub.cfg

Snapper rollback fails

# Rollback only works when booted from a read-only snapshot
# If you're on the live system, you need to reboot into a snapshot first

# Check if you're in a read-only snapshot
sudo btrfs property get / ro
# Should show "ro=true" if you're in a snapshot

Swapfile blocking snapshots

If you have a swapfile on Btrfs, it can block snapshot creation:

# Check if swap is a file
swapon --show

# If it's a file on /, you need to move it to a separate subvolume
# or switch to a swap partition
# See the openSUSE wiki SDB:BTRFS for details

Snapshots not being created automatically

# Check the Snapper plugin for zypper
rpm -q snapper-zypp-plugin

# Check the cleanup timer is running
systemctl status snapper-cleanup.timer

# Check Snapper logs
journalctl -u snapper-cleanup -u snapper-timeline --since today

Snapper Cheat Sheet

Print this. Stick it on your wall. You'll need it at 1am when something breaks.

Action	Command
List all snapshots	sudo snapper list
List with space info	sudo snapper list -a
Create a manual snapshot	sudo snapper create --description "reason"
Create a pre snapshot	sudo snapper create --type pre --description "reason"
Create a post snapshot	sudo snapper create --type post --pre-number N --description "reason"
See what changed	sudo snapper status 1..2
Diff a specific file	sudo snapper diff 1..2 /path/to/file
Undo all changes	sudo snapper undochange 1..2
Undo one file	sudo snapper undochange 1..2 /path/to/file
Delete a snapshot	sudo snapper delete 15
Delete a range	sudo snapper delete 10-25
Full rollback (from snapshot boot)	sudo snapper rollback && sudo reboot
View config	sudo snapper -c root get-config
Change config	sudo snapper -c root set-config KEY=VALUE
Check Btrfs usage	sudo btrfs filesystem usage /
Browse a snapshot	ls /.snapshots/5/snapshot/
Run cleanup	sudo snapper cleanup number