The store

store client for users for app developers for snapd developers for administrators

snapd asks one store a small set of questions. Search and info describe snaps. A channel name of track and risk and branch says which release to follow. One request reports every installed snap and returns the revisions to install or refresh. The file is then downloaded from the cache or as a delta or in full and checked by its SHA3-384 digest.

On the map: the harbour

▶ Watch this deck — 8 scenes, ~6 min

01 One address, a few questions

THE STORE $ sudo snap install photo-editorsnapd the storeapi.snapcraft.io searchsnap finddescribe one snapsnap info what should I install or refresh?snap install · snap refresh the file and the signatures that vouch for it
snap install photo-editor goes to snapd, which talks to the store at api.snapcraft.io: search, describe one snap, and the main question, what should I install or refresh; the store sends back the file and the signatures that vouch for it

snapd talks to one store, by default api.snapcraft.io. It searches, describes a snap, asks what to install or refresh, and then downloads the file and its signatures.

You type snap install, wait a few seconds, and the photo editor is there. What did your machine and the store actually say to each other? The snap command doesn't talk to the store itself. It asks snapd, and snapd does the talking, to one address by default. There are only a few kinds of question. Search. Describe one snap. And the main one: what should I install or refresh? The answer names a revision and where to download it. Then the file comes, and with it the signatures that let snapd trust it. The rest of this deck takes them one at a time.

02 Looking before you install

FIND AND INFO $ snap find photoName Version Publisher Notes Summaryphoto-editor 2.4 Example Studio - Edit and organise photosphoto-viewer 2.0.1 Example Studio - View photos quickly all channels by default--narrow: stable only Ubuntu Core: strict onlyclassic: strict and classic $ snap info photo-editorname: photo-editorpublisher: Example Studiotracking: latest/stable channels:latest/stable: 2.4 2026-10-02 (42) 96MB -latest/candidate: ↑latest/beta: ↑latest/edge: 2.5-dev 2026-11-10 (45) 97MB -1.x/stable: 1.9 2026-04-14 (30) 88MB -1.x/candidate: ↑1.x/beta: 1.10-beta 2026-05-20 (33) 89MB -1.x/edge: ↑version, release date,revision and sizefor every channel installed: 2.4 (42) 96MB -what you have
snap find photo prints name, version, publisher, notes and summary; it searches all channels unless --narrow is given, and asks only for confinement the system can run; snap info photo-editor prints the publisher, the tracked channel, one line per channel of the latest and 1.x tracks, in which 1.x/edge is closed, and the installed revision

snap find searches every channel unless you add --narrow, and asks only for confinement the system can run. snap info lists each channel of one snap with its version, date, revision and size. With no search term, snap find lists featured snaps.

Before you install anything, you can look. Two commands do the looking, and they ask the store two different questions. Snap find sends your words and prints a line per match: name, version, publisher, notes and a summary. It searches every channel, unless you add the --narrow option, which keeps it to stable. And it asks only for snaps your system can run, so on Ubuntu Core you'll see strictly confined ones only. Snap info asks about one snap by name. You get a line per channel, with its version, release date, revision and size. If it's installed, you also see what you're tracking and the revision you have.

03 A channel has three parts

CHANNELS track/risk/branch stable · candidate · beta · edgemore risk --channel=edgelatestedge --channel=1.x1.xstablenot a risk name, so it is a track --channel=1.x/beta/fix-crash1.xbetafix-crash stable and latest/stable are the same channel
A channel is track, risk and branch; the risks are stable, candidate, beta and edge; edge is read as latest/edge, 1.x as 1.x/stable, and 1.x/beta/fix-crash as track 1.x, risk beta, branch fix-crash; stable and latest/stable are the same channel

A channel is track/risk/branch. The risks are stable, candidate, beta and edge. A missing track means latest and a missing risk means stable, so edge is latest/edge and 1.x is 1.x/stable.

The photo editor has a stable release, a test release, and an older version 1 that some still want. One short name picks between them: the channel. It has up to three parts. The risk is the one you meet first: stable, candidate, beta, edge. You can leave parts out. Just edge means edge on latest, the track you get by default. 1.x isn't a risk name, so it's a track: a line of releases the publisher keeps side by side. A missing risk means stable. Add a branch, a short-lived line for one fix, and you've used all three. Plain stable and latest stable are the same channel.

04 Changing risk keeps the track

SWITCHING tracking:1.x/stable $ sudo snap switch --channel=edge photo-editor"photo-editor" switched to the "1.x/edge" channel 1.x/edgetrack keptnothing downloaded yet: the new revision comes with the next refresh $ sudo snap refresh --channel=edge photo-editorphoto-editor (1.x/beta) 1.10-beta from Example Studio refreshedswitches and installs in one step Channel 1.x/edge for photo-editor is closed; temporarily forwarding to 1.x/beta.1.x/edge has nothing released, so the store sends what 1.x/beta has; you keep tracking 1.x/edge in snap info, a closed channel shows ↑
Tracking 1.x/stable, snap switch --channel=edge switches photo-editor to 1.x/edge without downloading; snap refresh --channel=edge switches and refreshes in one step; 1.x/edge is closed, so the refresh brings the 1.x/beta release and says it is forwarding, while the tracked channel stays 1.x/edge; snap info marks a closed channel with an up arrow

A new channel that names only a risk keeps the current track: tracking 1.x/stable, asking for edge gives 1.x/edge. snap switch changes the tracked channel without a refresh; snap refresh --channel does both.

You're on the version 1 track and you'd like to try its edge build. Say edge, and snapd keeps the track you're on, so you end up on 1.x/edge. Snap switch only changes what you follow. Nothing is downloaded; the new revision comes with the next refresh. Snap refresh with the --channel option does both at once. And if your channel has nothing released on it, the store may hand you a revision from another risk of the same track. snapd tells you it's forwarding, and you keep tracking what you asked for. Snap info marks a closed channel like that with an up arrow.

05 Here is what I have, here is what I want for app developers for snapd developers for administrators

THE SNAP-ACTION REQUEST snapd on the gatewaythe storePOST v2/snaps/refresh contextevery installed store snap, one entry eachacme-agent revision 41 tracking-channel latest/stableepoch cohort-key held actionsrefresh acme-agentalso: install · download · fetch-assertions Snap-Device-Series · Snap-Device-ArchitectureSnap-Device-Store · Snap-Device-Authorizationwho is asking: the device, and you if you ran snap login result: refresh revision 42 sha3-384 download URL deltas download-snapvalidate-snap
snapd on the gateway posts to v2/snaps/refresh: a context entry for every installed store snap, such as acme-agent at revision 41 tracking latest/stable, and an action to refresh acme-agent, with device headers; the store answers with revision 42, its sha3-384 digest, a download URL and deltas, which become the download-snap and validate-snap tasks

Install, refresh and download share one request to v2/snaps/refresh: a context entry for every installed store snap and a list of actions. The result for each action becomes the download-snap and validate-snap tasks.

The gateway wants to know if there's a newer acme-agent. It doesn't ask about just that snap. It tells the store what it has, in two halves. The context lists every snap installed from the store: its revision, the channel it tracks, its epoch and cohort, and whether it's held. The actions say what's wanted: refresh acme-agent. Install, refresh and download all use it. Headers say which device is asking, and for which store. Each action gets an answer: a revision, its digest and where to fetch it, or an error such as no updates available. snapd turns that into two tasks: download-snap and validate-snap.

06 Cache, delta, or the whole file

THE DOWNLOAD acme-agent 42in the download cache?same digest, same size:use it 41a deltaonly the differencefrom revision 41 if the delta failsthe whole filea cut-off downloadresumes where it stopped SHA3-384 of a download = the digest the store sent full download mismatch: fetched once more from the start then the signaturesevery file hashed again
To get acme-agent revision 42, snapd tries the download cache, then a delta from revision 41, then the whole file, which can resume; a cached file is checked only by size at this point; a download, or a file rebuilt from a delta, must have the SHA3-384 digest the store sent, and a mismatched full download is fetched once more; every file, cached ones included, is then hashed again and that digest finds the signatures

The file comes from the download cache, from a delta applied to the installed revision, or as a full download that can resume. A download, or a file rebuilt from a delta, must match the store's SHA3-384 digest. Every file, cached ones included, is then hashed again, and that digest is the key of the snap-revision assertion that is fetched next.

Revision 42 is big and the gateway's link is slow. So snapd avoids fetching all of it. First, the cache: a file with the same digest may already be there. Next, a delta, if the store offered one: the difference from revision 41, applied to the copy of 41 on disk. If anything about the delta fails, snapd falls back to the whole file, and a full download that's cut off resumes where it stopped. A full download must match the store's SHA3-384 digest, or it's fetched again from the start. Whatever the route, snapd hashes the file once more, and that digest has to find its signed statement.

07 A different store, a proxy, or no store for administrators for snapd developers

FOR ADMINISTRATORS snapdthe defaultthe store $ sudo snap set system proxy.https=http://proxy.acme.example:3128snapdHTTP proxythe store $ sudo snap set system proxy.store=acme-proxysnapdevery address built on the url in its store assertionstore acme-proxy cannot set proxy.store to "acme-proxy" without a matching store assertionack the store assertion first $ sudo snap set system store.access=offlinesnapdthe store store is marked offline, use 'snap unset system store.access' to go onlineautomatic refreshes are skipped
By default snapd on the gateway talks straight to the store; proxy.https sends requests through an HTTP proxy; proxy.store sends them to the store acme-proxy, whose store assertion must be acknowledged first; store.access=offline cuts the line and every request fails with a message

proxy.http and proxy.https route requests through an HTTP proxy. proxy.store redirects them to the store whose assertion carries a url. store.access=offline makes every store request fail and skips auto-refresh.

Your gateways sit on a factory network with no direct route to the internet. Three settings help. The proxy options send every store request through an ordinary HTTP proxy. proxy.store goes further. It names another store by its id, and snapd builds every address from the URL in that store's assertion, so the assertion has to be acknowledged before the option is accepted. Changing it also drops the device's session, and the next request signs in to the new store. And store.access=offline stops snapd asking at all. Requests fail at once with a message saying how to go back online, and automatic refreshes are skipped.

08 Where to go from here

ROADS The store Snap packagingwhat is inside the downloaded fileAssertions: how they workthe signed statements with every snapAssertions: snaps and validationwhat the check after the download compares Refreshwhen snapd asks the store by itselfThe overlordthe change and tasks around a download Assertions: identity and storethe store assertion behind proxy.storeAssertions: devicesthe serial behind the device sessionsnapdback to the overview
Roads from the store: snap packaging, assertions and how they work, snaps and validation, refresh, the overlord, identity and store assertions, device assertions, and the snapd overview

Roads: packaging, assertions and the download check, refresh, the overlord, the store and device assertions, and the overview.

So that's the conversation: a few questions, one file, and a digest that has to match. Here's where the file goes next. Packaging opens it up and shows where it's mounted. The assertions decks cover the signed statements and the check that follows the download. Refresh shows when snapd asks the store without being told to. The overlord shows the change that the download was one task of. The identity and device decks cover the store assertion and the serial behind the device session. And the overview takes you back to the whole of snapd.

Read more

What snapd asks the store

QuestionEndpointAsked by
searchv2/snaps/findsnap find
describe one snapv2/snaps/info/<name>snap info, snap debug connectivity
install, refresh, download, fetch assertionsv2/snaps/refreshsnap install, snap refresh, snap download, auto-refresh; snap download sends it from the command itself, not through snapd
sectionsapi/v1/snaps/sectionssnap find --section, and snapd's periodic catalog refresh
categoriesv2/snaps/categoriesthe /v2/categories API of snapd; no snap command
create a cohortv2/cohortssnap create-cohort
device sessionapi/v1/snaps/auth/nonces, api/v1/snaps/auth/sessionssnapd, once the device has a serial

The default base address is https://api.snapcraft.io/. A request times out after 10 seconds. A failed request is retried up to 6 times within 38 seconds when the answer is a 5xx status or a transient network error; "no such host" is not retried.

Channel names

You writesnapd reads
stablelatest/stable
edgelatest/edge
1.x1.x/stable
1.x/betatrack 1.x, risk beta
beta/fix-crashrisk beta, branch fix-crash, track latest
1.x/beta/fix-crashtrack, risk and branch
four or more partserror: channel name has too many components

Risks in order: stable, candidate, beta, edge. Changing to a channel that names only a risk, or a risk and a branch, keeps the current track. A snap with no tracking channel is reported to the store as tracking stable. When the store answers an install with a redirect channel, for a snap whose publisher set a default track, snapd tracks that channel.

In snap info, ↑ (or ^) marks a closed channel in a track that has an open channel at a lower risk, and – (or --) one in a track with none.

for administrators for snapd developers

Pinned tracks on Ubuntu Core

When the model gives a track for the kernel or the gadget, a channel change may alter the risk but not the track. The error is cannot switch from kernel track "<track>" as specified for the (device) model to "<channel>" (or gadget track).

for app developers for snapd developers for administrators

The snap-action request

PartFields
context, one entry per installed store snapsnap-id, instance-key, revision, tracking-channel, epoch, refreshed-date, ignore-validation, cohort-key, validation-sets, held
actions, one entry per wanted operationaction (install, refresh, download, fetch-assertions), instance-key, name, snap-id, channel, revision, cohort-key, ignore-validation, epoch, validation-sets
request headersSnap-Device-Series, Snap-Device-Architecture, Snap-Classic, Snap-Device-Capabilities: default-tracks, Snap-Device-Store when the device has a store id, Snap-Accept-Delta-Format, Snap-Refresh-Managed, and Snap-Refresh-Reason: scheduled for an auto-refresh
result, one per actionresult (install, refresh, download, fetch-assertions, error), the snap's revision data, effective-channel, redirect-channel

A parallel instance is reported under a key derived from the snap id and a random salt kept on the device, so local instance names are not sent to the store. A requested revision equal to the installed one is not sent. A refresh result equal to what is installed becomes snap has no updates available.

The download

StepDetail
cache/var/lib/snapd/cache, keyed by SHA3-384; a hit must also have the right size
deltaformats xdelta3, and snap-1-1-xdelta3 first when experimental.snap-delta-format is on; applied to the installed revision's file in /var/lib/snapd/snaps; the rebuilt file must have the target's digest
full filewritten to <target>.partial, renamed at the end; resumes with a range request, or restarts when the server does not support it
digestsha3-384 mismatch for "<name>": got <a> but expected <b>; after one mismatch the file is downloaded once more from the start
retriesup to 7 attempts within 90 seconds
stalled transfercancelled when the average stays under 4096 bytes per second for 5 minutes
rate limitrefresh.rate-limit applies to auto-refresh downloads only
cache sizeat most 5 unreferenced files and 30 days; on Ubuntu Core also a 1 GiB target

A failed delta is logged as Cannot download or apply deltas for <snap>: <error> and the full download follows.

for app developers for snapd developers for administrators

What is fetched after the download

The validate-snap task computes the SHA3-384 digest and the size of the file and fetches the snap-revision assertion with that digest. Fetching it brings the snap-declaration, the publisher's and developer's account and the signing account-key chain. When the model names a store, the store assertion is fetched too. Components get snap-resource-revision and snap-resource-pair in validate-component. See Assertions and Snaps and validation.

A local file installed with snap install ./file.snap is not downloaded. snapd looks for assertions it already has for that file; snap ack adds them, and --dangerous installs without them.

for administrators for snapd developers

Who is asking

CredentialComes fromSent as
device sessionthe device signs a device-session-request with its device key and sends it with its serial and model assertionsSnap-Device-Authorization
usersnap login: e-mail, password and an optional one-time codeAuthorization

A device with no serial yet sends requests without device authorization. On an HTTP 401 snapd renews the expired credential and retries, up to 4 times per request. The store id in Snap-Device-Store is the store header of the model assertion; on a classic system with the generic model it is the UBUNTU_STORE_ID environment variable.

for administrators for snapd developers

Proxy, proxy store and offline

OptionEffect
proxy.http, proxy.https, proxy.ftp, proxy.no-proxyread for every store request, with the process environment as fallback; also written to /etc/environment
proxy.store=<store id>every endpoint is built on the url of that store assertion; setting it needs the assertion in the database; changing it resets the device session
store.access=offlineevery request and download fails; auto-refresh is skipped; the only other accepted value is unset

snap debug connectivity asks for the information of the snapd snap and then checks that the download host answers, and reports each host.

for administrators for snapd developers

Cohorts

snap create-cohort <snap> returns a cohort key. snap install --cohort=<key>, snap refresh --cohort=<key> and snap switch --cohort=<key> store it for the snap, and --leave-cohort clears it. The key is sent with every snap-action request, and snap info shows in-cohort. A cohort and a revision cannot be combined: cannot specify revision and cohort. What the key selects is decided by the store.

Messages you may meet

SituationMessage
no such snapsnap not found
nothing on that channelno snap revision on specified channel
nothing for this architectureno snap revision on specified architecture
already up to datesnap has no updates available
refresh of a snap installed from a local filecannot perform operation on local snap
search with --private while logged outyou need to log in first
too many requeststoo many requests
damaged downloadsha3-384 mismatch for ...
offlinestore is marked offline, use 'snap unset system store.access' to go online
no signaturescannot verify snap "<name>", no matching signatures found
paid snapplease buy <name> before installing it
search term with special charactersbad query

Further reading

  • Channels and tracks: what each risk level means, closed channels and snap switch.
  • Revisions: what a revision is and how to ask for one with --revision.
  • Snap deltas: download deltas and the fallback to a full download.
  • Network requirements: the hosts and ports snapd needs to reach.
  • Assertions: the signed documents that come with a snap.
  • Store overview: the global store, dedicated stores and how a device is bound to one.

Roads from here

START HERE

  • snapd — back to the overview

GETTING SNAPS

RUNNING SNAPS

  • Refresh — when snapd asks the store for refreshes by itself
  • The overlord — the change and tasks that carry a download

ASSERTIONS · signed statements snapd trusts