Remove and revert
snap lifecycle for users for administrators
snap revert goes back to the previous revision kept on disk with the data and settings that revision had. snap disable switches a snap off and keeps everything. snap remove deletes the snap and its data after saving an automatic snapshot unless --purge is given. refresh.retain sets how many revisions stay on disk.
On the map: running snaps district
01 Three ways to step back
snap revert goes back to the previous revision, snap disable switches the snap off and keeps everything, and snap remove deletes the snap and its data after saving a snapshot.
The photo editor refreshed this morning, and now it crashes every time you open a picture. What can you do about it, right now? Snapd kept the previous revision on disk for exactly this moment, so you have three moves. Snap revert puts that previous revision back, and nothing gets deleted. Snap disable switches the snap off and keeps everything, for when you want it out of the way while you find out more. Snap remove deletes the snap along with its data, and saves a snapshot of that data on the way out. We'll take them lightest first.
02 What stays on disk after a refresh
snap list --all shows the revisions on disk. A refresh keeps refresh.retain revisions, by default 2 on classic and 3 on Ubuntu Core, and discards the oldest with its per-revision data.
Before you revert, it helps to know what you can go back to. Ask snapd what it kept. snap list --all shows every revision on disk. 42, the one in use, has nothing under Notes, and 41 says disabled. The next refresh brings 43. It ends with a clean-up: the oldest revisions go until the allowed number is left, counting the new one. On classic that's two, so 41 goes and 42 becomes the one you can return to. Ubuntu Core keeps three. refresh.retain changes it, from two to twenty.
03 Revert puts the previous revision back as it was
snap revert activates the previous revision with the per-revision data and the configuration it had. Data the snap shares across revisions is not reverted. The newer revision stays on disk.
Each revision has its own copy of the snap's data, made at the moment of the refresh. So what does a revert give you back? snap revert photo-editor, and 2.3 is back: 41 was already on disk, so nothing is downloaded. The services stop and start again around the switch, but no refresh hooks run and no data is copied forward. So 41 gets its own data, as it was left this morning, and snapd restores the settings saved for 41. One thing isn't rolled back: the snap's common data, which every revision shares. If 42 converted something there, 41 finds it converted. And 42 stays on disk.
04 After a revert, the bad revision does not come back by itself
After a revert, a refresh of all snaps skips the revision that was reverted from. snap refresh photo-editor installs it again, and a newer revision refreshes normally.
You're back on 41. Tonight the timer fires again, and as far as the store is concerned, 42 is still the newest. Does it come straight back? No. When you revert, snapd marks the revisions you stepped back over, and leaves them out whenever it refreshes everything, on the timer or with a plain snap refresh. Name the snap, though, and the mark doesn't apply: snap refresh photo-editor takes you to 42 again. When the publisher releases 43, the next refresh installs it as usual, and the clean-up throws 42 away. And snap revert --revision goes to any revision that's still on disk, not only the previous one.
05 Disable switches a snap off and keeps everything
snap disable stops a snap's services and removes its commands; the revision, data and configuration stay. A disabled snap cannot be run, refreshed or reverted until snap enable.
Maybe you don't want the old version back either. You want it to sit still for a while. That's what disable is for. snap disable photo-editor stops its services and takes away its commands and its confinement profiles. The program, its data and its settings stay where they are. The command is gone now, and snap run tells you plainly that the snap is disabled. A refresh leaves it alone, and revert refuses it, so it stays at the revision it had. Snap enable links it back in and starts its services. Disable and enable are the two halves of a refresh, with no hooks and nothing in between.
06 Remove takes a snapshot, then deletes
snap remove stops services, runs the remove hook, saves an automatic snapshot, then deletes all revisions and data. --purge skips the snapshot. Automatic snapshots are kept 31 days on classic and are off by default on Ubuntu Core. --revision=<n> removes one inactive revision, with no snapshot. --terminate ends the snap's running processes after the remove hook, before the snapshot and the unlink.
You've decided: the photo editor has to go. Remove deletes your data along with the program, so watch the one thing it does first. Every revision goes, and all the snap's data, common data included. So the order matters. The services stop, and the snap's remove hook runs while it's still in place. Then snapd saves a snapshot of the data, and only then unlinks the snap and deletes anything. The output tells you a snapshot was saved. On a classic system it's kept for 31 days; on Ubuntu Core it's off unless you set a retention time. With the --purge flag, there's no snapshot and nothing to restore.
07 When snapd says no
Remove refuses the active revision, a snap required by the model or used for boot, and snapd while other snaps are installed. With a disk space reservation set and too little space for the automatic snapshot, it suggests --purge.
Sometimes remove says no. Each of these is snapd protecting something, and the message says what. You can't remove the revision that's in use: revert first, then remove the one you left. On classic, snapd itself goes last, after every other snap. On a device like the gateway, a snap the model requires can't be removed, nor can the kernel, gadget or base it boots with. With a disk space reservation set and no room for the snapshot, the error points you at the --purge flag, which removes the snap without taking one.
08 Where to go from here
Roads: snapshots, refresh, packaging, the remove hook, the kernel and base rollback and the overlord.
Revert, disable, remove: lightest to heaviest. Here's where the things they lean on are explained. The snapshots deck shows how to bring back the data that remove saved. The refresh deck covers the update that a revert undoes. Snap packaging explains revisions and where each one keeps its data. The hooks deck has the remove hook and what it can't do. On Ubuntu Core, try, trying, done shows the automatic revert of a kernel or base after a failed boot. And the overlord deck explains why each of these is a change you can watch.
Read more
Commands
| Command | Effect | Output |
|---|---|---|
snap revert <snap> | activate the previous revision | <snap> reverted to <version> |
snap revert --revision=<n> <snap> | activate a given revision that is on disk | the same |
snap disable <snap> | stop services, remove commands and profiles | <snap> disabled |
snap enable <snap> | link the snap again and start its services | <snap> enabled |
snap remove <snap> | delete all revisions and data after an automatic snapshot | <snap> removed (snap data snapshot saved) |
snap remove --purge <snap> | the same without a snapshot | <snap> removed |
snap remove --revision=<n> <snap> | delete one inactive revision and its data; no snapshot | <snap> (revision <n>) removed |
snap remove --terminate <snap> | after the services stop and the remove hook runs, end the snap's running processes, then take the snapshot and remove | |
snap list --all <snap> | show every revision on disk; older ones are noted disabled | |
snap set system refresh.retain=<n> | keep n revisions, 2 to 20 |
refresh.retain defaults to 2 on classic and 3 on Ubuntu Core. The clean-up at the end of each refresh first discards revisions newer than the current one (they exist after a revert), then the oldest until the allowed number is left, counting the new revision. Revisions that the device boots with are kept.
What each command keeps
| revert | disable | remove | remove --purge | |
|---|---|---|---|---|
| Other revisions on disk | kept | kept | deleted | deleted |
| Per-revision data | each revision keeps its own | kept | deleted | deleted |
| Common data | kept, not rolled back | kept | deleted | deleted |
| Configuration | the target revision's is restored | kept | deleted | deleted |
| Snapshot taken | no | no | yes, if the conditions hold | no |
| Services | restarted in the target revision | stopped | stopped | stopped |
A revert does not download or mount anything, runs no pre-refresh or post-refresh hook and copies no data. After it, a refresh of all snaps, by the timer or by a plain snap refresh, skips the revisions newer than the current one; snap refresh <snap> does not. A newer revision refreshes as usual and the clean-up then discards the skipped one.
When remove takes a snapshot
All of these must hold:
--purgewas not given;- the snap is of type
app; - all revisions are being removed;
- automatic snapshots are on: by default for 31 days on classic and off on Ubuntu Core;
snapshots.automatic.retentionsets a duration orno.
The free space for the snapshot is checked only when disk-reservation.size is set. With too little space, remove fails: cannot remove "<snap>" due to low disk space for automatic snapshot, use --purge to avoid creating a snapshot.
With snap data on NFS mounts, remove without --purge fails: cannot snapshot user data directories in NFS mounts: use --purge to skip taking a snapshot.
How to list, restore and forget the snapshot is in Snapshots.
Messages
| Message | Meaning |
|---|---|
no revision to revert to | no previous revision is on disk |
already on requested revision | --revision names the current one |
cannot revert inactive snaps | the snap is disabled |
cannot find revision <n> for snap "<name>" | that revision is not on disk |
cannot remove active revision <n> of snap "<name>" (revert first?) | --revision names the revision in use |
cannot terminate running apps unless all revisions are removed | --terminate with --revision |
snap "<name>" is not removable: snap is being used for boot | a kernel or base revision the device boots with |
snap "<name>" is not removable: snap is used by the model | the model's kernel, gadget or base |
snap "<name>" is not removable: snap is required | required by the model |
snap "<name>" is not removable: snapd required on core devices | snapd on Ubuntu Core |
snap "<name>" is not removable: remove all other snaps first | snapd on classic |
snap "<name>" is required by validation sets: <sets> | an enforced validation set requires it |
snap "<name>" cannot be disabled | gadget, kernel, base and core (os) snaps |
snap "<name>" already disabled, snap "<name>" already enabled | nothing to do |
refreshing disabled snap "<name>" not supported | snap refresh <name> of a disabled snap; a refresh of all snaps skips it |
cannot update disabled snap "<name>" | installing a snap file over a disabled snap |
cannot run "<name>", snap is disabled | snap run of a disabled snap; its commands are removed |
cannot run "<name>", snap is being removed | starting an app during removal |
cannot clear snap data due to unknown active mounts at: ... | something is mounted inside the snap's data |
The snap command prints the errors from snap remove and snap refresh with the prefix cannot remove "<name>": or cannot refresh "<name>": .
for administrators
Tasks
Remove, all revisions: stop-snap-services, run-hook (remove), auto-disconnect, kill-snap-apps (with --terminate), save-snapshot (unless --purge), remove-aliases, unlink-snap, remove-profiles, then clear-snap and discard-snap for each revision, the current one last.
Revert: the refresh chain starting at prepare-snap, without download-snap, mount-snap, the pre-refresh and post-refresh hooks, copy-snap-data and the removal of old revisions.
Disable: stop-snap-services, remove-aliases, unlink-snap, remove-profiles. Enable: prepare-snap, setup-profiles, link-snap, setup-aliases, start-snap-services.
Further reading
- Get started: remove, purge and revert in tutorial form.
- Manage updates: the section "Revert to an earlier revision" and
refresh.retain. - Revisions: what a revision is and how data follows it.
- Data locations: which directories are per revision and which are common.
- Decommissioning: what is left on a system after snaps are removed, including saved snapshots.
Roads from here
GETTING SNAPS
- Snap packaging — revisions and where a snap keeps its data
- Epochs: when new code cannot read old data — when a revert crosses an epoch
RUNNING SNAPS
- Snapshots — the snapshot taken on removal and how to restore it
- Refresh — the refresh that a revert undoes
- The overlord — remove and revert are changes
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — the remove hook and what it cannot do
UBUNTU CORE · boot
- Try, trying, done — the automatic revert of a kernel or base