Refresh

snap lifecycle for users for administrators for Ubuntu Core developers for snapd developers

snapd checks the store four times a day by default and refreshes every snap that has a new revision. A refresh can be held for all snaps or for named snaps. A snap with a running app is downloaded ahead and refreshed when the app closes or after 14 days. Each refresh is a change that stops the snap's services and switches revisions and it ends by asking the store once more.

On the map: the clocktower

▶ Watch this deck — 8 scenes, ~6 min

01 Nobody asked for this update

REFRESH 00:0006:0012:0018:0024:00 00:00~24:00/4four windows a day a random moment in each window ask the storenew revisions?refresh them $ snap refresh --timetimer: 00:00~24:00/4last: today at 09:12 UTCnext: today at 14:47 UTClast: the last attempt, refreshed or not the timetable says when a refresh may start;a hold, an open app or an unready devicecan still postpone itthe rest of this deck: when it is allowed, how to hold it, what happens to open apps and to services
A day from 00:00 to 24:00 split into four windows by the default timer 00:00~24:00/4, with one random moment in each; at one moment snapd asks the store, finds new revisions and refreshes them; snap refresh --time prints the timer, the last attempt and the next one

By default snapd checks for new revisions four times a day, at a random moment in each of four windows (00:00~24:00/4). snap refresh --time shows the timer, the last attempt and the next one.

You open your laptop and the photo editor has a new version. You didn't ask for that, so who did, and when? Snapd keeps a timetable. By default it splits the day into four windows and picks a random moment inside each, so that not every machine asks the store in the same minute. At that moment it asks the store about every installed snap, and refreshes the ones that have a new revision. snap refresh --time shows the timer, the last attempt and the next one. A timetable says when a refresh may start, though. A few things can still postpone it.

02 The questions snapd asks before it starts for administrators for Ubuntu Core developers for snapd developers

BEFORE IT STARTS ensure loop1 · store not set offline?store.access=offline: do nothing 2 · device ready?seeded · serial or 3 tries · clock synced or 10 min 3 · no auto-refresh running?one auto-refresh change at a time 4 · not held?refresh.hold5 · next time reached?refresh.timer, from last-refresh 6 · not on a held metered link?refresh.metered=holdoff by default; 95 days at most auto-refresh changeone store query, then no new attempt for at least 20 minutes
From the snap manager's ensure loop down to an auto-refresh change, six checks in order: the store is not set offline, the device is ready, no auto-refresh change is running, no hold, the next time has come, not held on a metered connection; then one store query, and the next attempt no sooner than 20 minutes later

Before an auto-refresh snapd checks, in order: the store is not set offline, the device is seeded, has a serial (or has failed three times to get one) and a synced clock, no auto-refresh change is in progress, no hold, the scheduled time has come, not held for a metered connection. Store queries are at least 20 minutes apart.

The timer says it's time. That's one of six questions snapd asks, and not the last. It walks the same list every time it wakes up. Is the store set offline? Is the laptop ready: seeded, with a serial, and a synced clock or ten minutes' wait? Is an earlier auto-refresh still running? Is a hold in place? Has the next time on the timer arrived? And is the connection metered, with refresh.metered set to hold? That's off unless you set it, and gives up after 95 days. Only then does it ask the store, and not again for 20 minutes.

03 Two kinds of hold

HOLD $ snap refresh --holdAuto-refresh of all snaps heldindefinitely auto-refreshheldsnap refreshrunssnap refresh photo-editorrunsthe system option refresh.hold $ snap refresh --hold=72h photo-editorGeneral refreshes of "photo-editor"held until 2026-11-16T10:00:00Z auto-refreshheldsnap refreshheldsnap refresh photo-editorrunsyou named the snap, so it is refreshed no duration means forever: the code applies no limit to a hold you place · a held snap shows "held" under Notes in snap list $ snap refresh --unhold$ snap refresh --unhold photo-editorlifts the hold on all snapslifts only the hold on photo-editor
Two holds side by side. snap refresh --hold holds only auto-refresh; snap refresh and snap refresh photo-editor still run. snap refresh --hold=72h photo-editor holds auto-refresh and snap refresh for that snap, but snap refresh photo-editor still runs. No duration means forever; --unhold without names removes the hold on all snaps and --unhold photo-editor removes that snap's hold

snap refresh --hold holds the automatic refresh of all snaps; it is the system option refresh.hold. snap refresh --hold photo-editor holds that snap in every refresh of all snaps, but snap refresh photo-editor still refreshes it. A hold with no duration lasts until --unhold, given without names for the first kind and with the snap's name for the second.

You're away for a week and you'd like the photo editor to stay as it is. There are two ways to say that. snap refresh --hold, with no snap names, holds the automatic refresh of every snap; you can still refresh by hand. Name the photo editor, and snapd holds general refreshes of that snap: the automatic one and a plain snap refresh both skip it. snap refresh photo-editor still refreshes it, because you named it. Give a duration, like 72 hours, or none: that's forever, with no cap. snap refresh --unhold with no names lifts the first kind; name the snap to lift the second.

04 The app is open when the update arrives

THE APP IS OPEN photo editor · openrevision 41 update foundrevision 42 downloaded, not installed you close the apprefresh to 42 $ photo-editorsnap package "photo-editor" is being refreshed, please waitstarted during the switch:it waits, then opens 42 14 daysrefreshed even if still openno desktop helper?snap warnings reminds you $ snap refresh photo-editorsnap "photo-editor" has running apps (photo-editor), pids: 4242by hand, an open appis an error
A timeline: the photo editor is open on revision 41; an update is found and revision 42 is downloaded but not installed; when you close the app it is refreshed to 42; starting it during the switch waits; after 14 days it is refreshed even if still open; a manual snap refresh of an open app fails with has running apps

While one of a snap's apps is running, its automatic refresh is postponed: the new revision is downloaded, and installed when the app closes or after 14 days. A manual refresh of a snap with a running app fails with has running apps.

You've had the photo editor open all afternoon, and an update arrives. Swapping a program out from under you isn't safe, so snapd doesn't. It downloads the new revision now and leaves it waiting. When you close the app, the refresh runs straight away. Start it again in those few seconds and it waits, then opens the new revision. Keep it open for 14 days, though, and snapd refreshes it anyway. Unless a desktop helper snap is watching refreshes, snap warnings reminds you to close the app. And snap refresh photo-editor, run by hand while it's open, fails, naming the app and its process ids.

05 How snapd waits for the app for administrators for Ubuntu Core developers for snapd developers

INHIBITED 1 · soft checkrunning apps?services do not count pre-downloadchangepre-download-snaptask 2 · watchsnapd watches thesnap's cgroupscandidate marked monitored,restored after a snapd restart 3 · last process exitsauto-refreshchange for this one snap unlink-current-snapchecks again holding the runinhibition lock, hint refreshsnap runwaits refresh.max-inhibition-days1 to 21, default 14after that: refresh with apps runningan app can opt out with refresh-mode: ignore-runningsnaps cannot hold their own refresh any more: the gate-auto-refresh hook is retired
Three stages: a soft check for running apps turns a busy snap's auto-refresh into a pre-download change with a pre-download-snap task; snapd watches the snap's cgroups; when the last process exits an auto-refresh change runs for that snap, where unlink-current-snap checks again under the run inhibition lock and snap run waits; refresh.max-inhibition-days, 1 to 21 and 14 by default, bounds the wait

A busy snap gets a pre-download change. snapd then watches its processes and creates an auto-refresh change when the last one exits. The unlink-current-snap task repeats the check under the run inhibition lock. refresh.max-inhibition-days (default 14) bounds the wait.

Putting a refresh off until you close the app sounds simple. Here's what it takes to do it without a gap where the app could start again. First, a soft check: which of the snap's apps have processes? Services don't count. A busy snap gets a separate pre-download change that only fetches it. Then snapd watches the snap's control groups, and when the last process exits it creates an auto-refresh change for that one snap. There, unlink-current-snap checks again while holding the run inhibition lock, so snap run waits instead of starting. refresh.max-inhibition-days, 14 by default, caps the whole wait.

06 One snap, from revision 41 to 42 for administrators for Ubuntu Core developers for snapd developers

THE CHANGE download-snapvalidate-snapmount-snapauto-refresh · Auto-refresh snap "acme-agent"fetch and check41 still running run-hook pre-refreshstop-snap-servicesruns in 41 unlink-current-snapcopy-snap-datasetup-profileslink-snapswitch run-hook post-refreshstart-snap-servicesruns in 42 acme-agent.agent is down discard revisions beyond refresh.retainrun-hook configurerun-hook check-healthtidy upa kernel, gadget or base adds boot tasks and a reboot · a service with refresh-mode endure is not stopped
The tasks of one snap in an auto-refresh change for acme-agent, in order: download-snap, validate-snap and mount-snap while 41 runs; the pre-refresh hook in 41 and stop-snap-services; unlink-current-snap, copy-snap-data, setup-profiles and link-snap; the post-refresh hook in 42 and start-snap-services; then old revisions are discarded and the configure hook and check-health run. The service is down from stop-snap-services to start-snap-services

Per snap, a refresh downloads, validates and mounts the new revision while the old one runs, then stops services, unlinks, copies data, sets up profiles, links, and starts services. The services are down between stop-snap-services and start-snap-services. A failure undoes the tasks in reverse and 41 comes back.

Now a different machine. On the gateway there's no app to close, just a daemon that should be running. So how long is acme-agent down while it goes from 41 to 42? Everything that can happen while 41 runs happens first: download, check, mount. Then 41's pre-refresh hook runs and the services stop. The current revision is unlinked, its data copied for 42, the security profiles set up, and 42 is linked. The post-refresh hook runs in 42 and the services start. So the agent is down from stop to start, and no longer. Then snapd tidies up: old revisions, the configure hook, the health check.

07 The change ends by asking the store again for administrators for Ubuntu Core developers for snapd developers

RE-REFRESH one changeacme-agent 41 → 42 · done check-rerefreshwaits until every other task is ready storeonly the snaps refreshed here No re-refreshes found.usually: the change ends Found re-refresh for acme-agent.its tasks join the same changeacme-agent 42 → 43 taken only when the offered revision's epoch differs from the installed one: a data format that moves on in steps
One change: acme-agent 41 to 42 is done, and the last task, check-rerefresh, waits for the others and asks the store about only the snaps refreshed in this change. Usually no re-refresh is found and the change ends; when one is found, acme-agent 42 to 43 is added to the same change. An update is taken only when its epoch differs

check-rerefresh is the last task of a refresh change. It asks the store again for the snaps the change refreshed and, when a revision with a different epoch is offered, adds its tasks to the same change.

Forty-two is running and the agent is back up. The change still isn't done, and the task that's left looks odd: it goes back to the store. That's check-rerefresh. It waits until every other task is ready, then asks the store again, but only about the snaps this change refreshed. Usually the answer is nothing. It's there for a snap whose data format moved on in steps, which the snap marks with its epoch. The store first offers a revision that can read the old data, and only from there the latest one. So when the data format moves on in steps, you get both steps in one change.

08 Where to go from here

ROADS RefreshThe overlorda refresh is a change of tasks The storenew revisions and channels Servicesstopped and started around it Remove and revertold revisions, back to 41 Try, trying, donekernel and base on Ubuntu Core Assertions: snaps and validationvalidation sets pin revisions
Roads from Refresh: the overlord, the store, services, remove and revert, try trying done for kernels and bases, and assertions for validation sets

Roads: the overlord, the store, services, remove and revert, the kernel try and validation sets.

A timetable, a few reasons to wait, and a column of tasks. Here's where each piece is explained in full. The overlord deck shows what a change and its tasks are, and how a failure is undone. The store deck covers where new revisions and channels come from. The services deck shows how a daemon is stopped and started around a refresh. Remove and revert covers the old revisions kept on disk, and going back to 41. The try deck covers what a kernel or base refresh adds on Ubuntu Core. And validation sets, which pin revisions during a refresh, live with the snap assertions.

Read more

Refresh options

Set with snap set system <option>=<value>.

OptionValuesEffect
refresh.timera timer string; default 00:00~24:00/4; managedwhen auto-refresh may start. A value that cannot be parsed is logged and the default is used
refresh.schedulelegacy scheduleread only when refresh.timer is empty
refresh.holdan RFC 3339 time or foreverno auto-refresh until that time. No upper limit is applied
refresh.meteredhold or unsetwith hold, no auto-refresh on a metered connection, for at most 95 days since the last refresh
refresh.retain2 to 20; default 2 on classic and 3 on Ubuntu Corerevisions of each snap kept on disk
refresh.max-inhibition-days1 to 21; default 14how long a running app can postpone its snap's auto-refresh
refresh.rate-limita byte sizelimits the download rate of auto-refreshes

refresh.timer=managed is accepted only when an installed snap from the store has a connected snapd-control plug with refresh-schedule: managed. snapd then starts no auto-refresh by itself.

An auto-refresh waits until the device is seeded, its clock is synchronised or 10 minutes have passed, and it has a model and a serial. snapd also starts an auto-refresh without a serial after three failed attempts to get one.

On classic, a freshly seeded system gets refresh.hold set two hours ahead when no hold is set.

Commands

CommandEffect
snap refreshrefresh every snap that has a new revision, except held ones
snap refresh <snap>refresh that snap, also when it is held
snap refresh --listshow what a refresh would do
snap refresh --timeprint timer:, last:, hold: and next:; a held next refresh reads next: <time> (but held); last: is the last auto-refresh attempt that reached the store, not the last successful refresh
snap refresh --hold[=<duration>]hold auto-refresh of all snaps; prints Auto-refresh of all snaps held ...
snap refresh --hold[=<duration>] <snap>...hold general refreshes of those snaps; prints General refreshes of ... held ...
snap refresh --unhold [<snap>...]without names, remove the hold on all snaps; with names, remove those snaps' holds
snap refresh --transaction=all-snapsall snaps refresh or none; the default is per-snap
snap refresh --ignore-validation <snap>refresh without applying validation sets
snap warningsshows cannot refresh (<snaps>) due running apps; close running apps to continue refresh. while a running app postpones a refresh and no snap has snap-refresh-observe connected; it can return soon after snap okay

Two holds

Hold on everythingHold on named snaps
Commandsnap refresh --holdsnap refresh --hold <snap>
Levelauto-refreshgeneral
Stored asthe system option refresh.holdan entry per snap, holder system
Auto-refreshheldheld
snap refreshrunsskips the snap
snap refresh <snap>runsruns
Limitnonenone

A general hold on all snaps is refused: holding general refreshes for all snaps is not supported. A held snap shows held under Notes in snap list.

Three mechanisms with similar names

  • A hold placed by the administrator, described above. This is the only hold snapd applies today.
  • The gate-auto-refresh hook and snapctl refresh --hold, with which a snap could hold its own or a dependent snap's refresh for up to 90 days. The feature is permanently disabled; see snapctl: services, refresh and changes.
  • "Refresh control" in the Ubuntu Core documentation: a gating snap and validation assertions. See Assertions: snaps and validation.

Validation sets during a refresh

  • An auto-refresh first refreshes assertions, including validation sets.
  • A refresh of all snaps applies the sets that are in enforce mode. A pinned revision replaces the requested one. A snap whose presence is invalid fails with cannot refresh snap "<name>" due to enforcing rules of validation set <set>.
  • Parallel instances are not constrained.

for administrators for Ubuntu Core developers for snapd developers

Tasks of one snap in a refresh change

In order: prerequisites, download-snap, validate-snap, mount-snap, run-hook (pre-refresh), stop-snap-services, remove-aliases, unlink-current-snap, copy-snap-data, setup-profiles, link-snap, auto-connect, set-auto-aliases, setup-aliases, run-hook (post-refresh), start-snap-services, clear-snap and discard-snap for each revision beyond refresh.retain, cleanup, run-hook (configure), run-hook (check-health). One check-rerefresh task ends the change. Kernel, gadget and base snaps add boot tasks; see Try, trying, done.

Change kinds: auto-refresh (summary Auto-refresh snap "<name>", Auto-refresh snaps ... or Auto-refresh <n> snaps) and pre-download (summary Pre-download <names> for auto-refresh).

A failed task undoes the tasks before it in reverse order and the old revision returns; see The overlord.

for administrators for Ubuntu Core developers for snapd developers

When an auto-refresh fails

  • A snap whose switch was undone is recorded with the revision that failed. Auto-refresh to that same revision is delayed, starting at 8 hours and growing to 2 weeks, and the delay is doubled when a kernel, gadget, boot base or snapd refresh failed after its reboot. A different revision is tried at once.
  • snap refresh <snap> by hand is not delayed.

for administrators for Ubuntu Core developers for snapd developers

Refresh awareness in detail

ItemValue
What makes a snap busya running app that is not a service and does not set refresh-mode: ignore-running; a running hook other than a confdb hook
Not checkedsnaps of type snapd and os
Error on a manual refreshsnap "<name>" has running apps (<apps>), pids: <pids>
Lock file/var/lib/snapd/inhibit/<snap>.lock
Hintsrefresh, pre-download, remove, disable
snap run during a refreshwaits, polling every 500 ms; on a terminal, when no snap has snap-refresh-observe connected, prints snap package "<name>" is being refreshed, please wait
Noticesrefresh-inhibit and snap-run-inhibit (reading them needs snap-refresh-observe), change-update
Desktop notificationsnapd posts none itself. A snap with snap-refresh-observe connected, such as a desktop integration snap, reads the notices and tells the user
Fallback warningcannot refresh (<snaps>) due running apps; close running apps to continue refresh., when no snap has snap-refresh-observe connected. It is meant to return 24 hours after snap okay, but snapd re-creates it at every auto-refresh attempt while the app is still open, so it can return within hours (a snapd bug)

Further reading

Roads from here

GETTING SNAPS

  • The store — where new revisions and channels come from

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

UBUNTU CORE · boot

DESKTOP · snaps in a user session