System options


Snap supports a set of system-wide options that allow you to customise your snap environment.

As with Configuration in snaps, these options are changed with the set and get commands, but with a target of system instead of a specific snap:

$ snap set system some.option="some value"
$ snap get system some.option

Controlling refresh frequency

There are three system-wide options that are used to manage various aspects of your snap environment handles update frequency:

  • refresh.timer: defines the refresh frequency and schedule
  • refresh.metered: pauses refresh updates when network connection is metered
  • refresh.retain: sets how many revisions of a snap are stored on the system


Use refresh.timer to modify when, and how frequently, your snaps are refreshed.

The following example asks the system to only refresh snaps between 4.00am and 7.00am, and 7.00pm and 10:10pm:

$ sudo snap set system refresh.timer=4:00-7:00,19:00-22:10 

Other examples for the time and frequency option include:

Options Result
mon,10:00,,fri,15:00 Mondays at 10:00, Fridays at 15:10
mon,fri,10:00,15:00 Mondays at 10:00 and 15:00, Fridays at 10:00 and 15:00
mon-wed,fri,9:00-11:00/2 Monday to Wednesday and on Friday, twice between 9:00 and 11:10
mon,9:00~11:00,,wed,22:00~23:00 Mondays, some time between 9:00 and 11:00, and on Wednesdays, some time between 22:00 and 23:00
mon,wed Monday and on Wednesday, at 0:00
mon2-wed2,23:00-24:00 Monday through Wednesday on the 2nd week of the month, between 23:00 and 24:00
fri5,23:00-01:00 Last Friday of the month, from 23:00 to 1:00 the next day

See Timer string format for a comprehensive breakdown of the syntax used to define times and frequencies.

You can check the update frequency for your environment with the refresh command:

$ snap refresh --time
timer: 00:00~24:00/4
last: today at 07:47 BST
next: today at 12:13 BST

By default, the snap system is scheduled to refresh four times per day, as shown in the above output.


Use refresh.metered to pause and re-enable the refresh process when NetworkManager detects a metered connection, such as an LTE link with a limited data plan.

To hold refreshing snaps when on a metered connection:

$ sudo snap set system refresh.metered=hold

To allow refreshing:

$ sudo snap set system refresh.metered=null

By default, refresh is enabled when a metered connection is detected.


Use refresh.retain to set the maximum number of a snap’s revisions stored by the system after the next refresh:

$ sudo snap set system refresh.retain=3

The refresh.retain value can only be a number between 2 and 20 and has a default value of refresh.retain=3.


These options may be set to change the proxies to be used by the system when communicating with external sites that speak the respective protocols.

Available since snapd 2.28.


May be set to true for disabling the SSH service at startup.

Available since snapd 2.22.


Defines the behavior of the system when the power key is pressed.

May be set to one of:

  • ignore
  • poweroff
  • reboot
  • halt
  • kexec
  • suspend
  • hibernate
  • hybrid-sleep
  • lock

Available since snapd 2.23.


Changes various settings that land onto Rasperry Pi’s traditional config.txt file.

The following options are currently available for tuning:

  • pi-config.disable-overscan
  • pi-config.framebuffer-width
  • pi-config.framebuffer-height
  • pi-config.framebuffer-depth
  • pi-config.framebuffer-ignore_alpha
  • pi-config.overscan-left
  • pi-config.overscan-right
  • pi-config.overscan-top
  • pi-config.overscan-bottom
  • pi-config.overscan-scale
  • pi-config.display-rotate
  • pi-config.hdmi-group
  • pi-config.hdmi-mode
  • pi-config.hdmi-drive
  • pi-config.avoid-warnings
  • pi-config.gpu-mem-256
  • pi-config.gpu-mem-512
  • pi-config.gpu-mem

Please see the Raspberry Pi documentation for details on their meanings.

Disabling automatic refresh for snap from store
Refresh-schedule via core config
Special casing the core configuration
Disabling automatic refresh for snap from store
Snap Documentation
Released: snapd 2.23.6
Snapd 2.35.2: ERROR run hook "configure": cannot set "core.schedule": unsupported system option
Using the forum to host documentation
Launcher items disappear and reappear on refresh

I’ve transformed the post into a wiki, reformatted the options to be a bit more readable, and fixed them so that they use dashes instead of underscores which is what’s supported.

@mvo Hopefully I’m not mistaken about your intent here.


It would be great if we can get all these added to which also has an explanatory description of each available option.

Also why do we have device specific options on the core snap? What does happen if I set pi-config.disable-overscan on a device not a pi? Will I see default values for those?


i guess long term that should move to the gadget snaps … and we are still missing a lot of options that will make users still edit the file by hand.


@morphis This page should be removed and link here instead. This is a pattern we should try to replicate with other pages in the documentation. We’ll have many more contributing eyes here, and everyone is able to immediately fix broken documentation, take feedback, and improve it right then.

@davidcalle Can you help us with that?

@ogra Before we move this out of core, we need to have a better picture of how gadget updates are taking care of boot assets, etc. We don’t want to hand off control of these sensitive configuration files before we do that as depending on how we do these updates we might brick devices in the field. Note that having it in core already allows gadgets to tune these options nevertheless.


yup, fully agreed, but what will the migration path for vendors that start using this in their images today be ?
if we move it later we somehow need to move their products too, to not break them with a core update that suddenly does not have that feature anymore …


There’s no reason for us to break the support in core.


Included refresh.schedule and transformed it into something more prosaic.


What time zone is refresh.schedule in? I would have assumed the system time zone, but snap changes for example shows timestamps in UTC.


The proposed implementation is using system’s local time.


Can someone document ‘timer’ as well with the complete syntax and representative cron/anacron replacement examples? (eg, hourly, daily at midnight, etc)


Until that happens, one can look at ParseSchedule() at


I’ve added most common formats to this topic: Timer string format


I was trying to set the refresh timer to 1st Wednesday of the month at 13:00 and used the convention wed1,13:00. I was expecting the next refresh timer to be set to 1st August which is two days from today (30th of July 2018) but it is set to Wednesday of the second week of August . Is this a bug or am I doing something wrong ?

Here is my commands

$ sudo snap set system refresh.timer=wed1,13:00
$ sudo snap get system refresh.timer
$ sudo snap refresh --time
timer: wed1,13:00
last: 11 days ago, at 12:33 IST
next: in 9 days, at 13:00 IST


Thanks for reporting this. This looks like a bug in calculating the time, I’ll look into it.

Edit: The fix is waiting for review atm.


Using the latest Edge image for Core, setting pi-config.display-rotate=1 (or manually editing /boot/uboot/config.txt) results in a dysfunctional system. According to the official documentation for config.txt video options, display_rotate is deprecated and one should use display_hdmi_rotate or display_lcd_rotate. Setting either manually in /boot/uboot/config.txt seems to have no effect.
Do I need to change any of the HDMI-related parameters as well, or is this a known issue in Edge? When I use Core stable, using the snap configuration hook for display_rotate works as expected.

(ping @ogra for Pi-related things IIRC :blush: )


AFAIK the rotate options only apply to the raw framebuffer that the Pi firmware initalizes.

we default to use the kms/drm framebuffer driver in our pi gadgets though, can you try commenting dtoverlay=vc4-kms-v3d in config.txt and see if the rotation options work then …

if this fixes it, we probably need to make sure the snapd code disables the overlay (at the cost of any accelerated graphics support) in case one of these rotate options gets set.


Will try out disabling the overlay as you suggested, but I’d be happy to use other methods if they preserve accelerated graphics support. Do you happen to have a solution for display rotation with kms/drm, preferably one that can be changed without a reboot?


Is there a preferred mechanism to unset a configuration item?

Let’s say that I want to set a proxy:

$ sudo snap set system proxy.https="localhost:9000"

And later on, I wish to remove that proxy by setting the key to an empty string:

$ sudo snap set system proxy.https=""

That item now still appears within the config:

$ sudo snap get system proxy.https
Key          Value

Is it possible to delete the key?