Your rating: None Average: 5 (41 votes)

Scripts for safe and automated upgrading of SailfishOS with logging

Upgrading SailfishOS at the GUI (per Settings -> SailfishOS updates) provides very little information about its progress / process / success, beyond reading /var/log/systemupdate.log after an upgrade. This can make troubleshooting issues hard.
Furthermore the GUI offers no control which SailfishOS version to upgrade to.

In contrast to that, Jolla's guide how to upgrade SailfishOS at the command line offers full control, while lacking any logs or safety checks.
Furthermore it is tedious and error prone to issue multiple, critical commands manually at the command line.

sfos-upgrade performs the steps to upgrade SailfishOS at the command line in an automated manner, while providing extensive safety measures plus full log output at the screen and in a log file.

Safety measures:

  • Check free space on the root filesystem.
  • Check BTRFS allocation, if the root filesystem uses BTRFS.
  • Check battery state (since v1.0).
  • Check if upgrading to a correct and available SailfishOS version.
  • Check if omitting (i.e., "jumping over") a stop release (since v0.3).
  • Automatically unapply all Patches, if Patchmanager is installed.
  • Stop systemd services for cron, btrfs-balance-checker etc. (since v2.2).
  • Terminate running processes, which may disturb upgrading SailfishOS (since v2.7).
  • Disable all OpenRepos' repositories, when upgrading from a SailfishOS version below 1.0.4 (since v0.4).
  • Emit a warning when downgrading.
  • Prevent downgrades, which would likely break the SailfishOS installation (since v3).

Usage (as root user):

  • sfos-upgrade [<version>]
    With a version number provided as parameter, it sets SSU to this version and in release mode before upgrading. This is the regular use case.
    Without a version number, it retrieves the one set for SSU to perform slightly relaxed checks, but does not alter SSU's settings for upgrading.  Hence the version to upgrade to and SSU's "release mode" have to be set (per e.g., ssu re <version>) before executing sfos-upgrade without a parameter.
  • sfos-upgrade --verify
    Performs a "samegrade" operation, i.e. checks if the correct versions of all recent RPMs are installed and updates or installs them accordingly.
    This option was introduced with v3.7.0.
  • sfos-upgrade -?|--help
    Emits a brief usage description.

When an upgrade succeeded, reboot, and do not miss to run post_sfos-upgrade (as root) then!
Not running it will result in an huge upgrade log file (containing many duplicate entries), plus may result (as any SailfishOS upgrade at the command line without tidying efforts afterwards) in RPMs failing to install (with "unmet dependency" / "Fatal error: nothing provides X needed by Y" errors) and annoying notifications from the store-client that an upgrade to the installed version is available.

Logs are originally written to /var/log/systemupdate_*.log-dupes.txt and tidied by tidy_log-dupes (which is called by post_sfos-upgrade) to /var/log/systemupdate_*.log.txt.


  • All operations comprise the RPMs from all enabled repositories, because that is version --dup's implicit behaviour (as with pkcon upgrade-system and zypper dist-upgrade / zypper dup too, all utilising libzypp).
  • When upgrading from a long outdated SailfishOS version (e.g., after a "factory reset"), sfos-upgrade eases and speeds up the process of upgrading to a recent SailfishOS release via consecutively installing all "stop releases" on the way.
    Simply run sfos-upgrade <intended version>, reboot, and repeat: it will guide you through all stop releases.
    Omit running post_sfos-upgrade between consecutive SailfishOS upgrades (but do reboot each time!), only run it once after having upgraded to the intended version.
  • To ensure that a SailfishOS installation is complete and up to date, use sfos-upgrade --verify; this will "samegrade" to the installed version, which is as close as one can get to the version --verify lost since SailfishOS 2.2.1 (which only checked for missing or not up-to-date RPMs, while "samegrading" will also install them) without zypper. With it (per pkcon install zypper), a zypper refresh && zypper verify --dry-run comes closer to what version --verify did (only checking). While zypper can also be used for up-/down-/same-grading, that is rather a "last resort"-measure than the primary recommendation, hence use sfos-upgrade for that.
  • sfos-upgrade supports all public SailfishOS releases and should work fine for upgrading from / to any release (it accepts only version numbers of at least at the command line, but omits this check when called without a parameter after utilising ssu to pre-set a version to upgrade to).
  • sfos-upgrade is simply a frontend for ssu re and version --dup, performing a multitude of checks before initiating the upgrade proper, while post_sfos-upgrade carries out the "Final clean up" steps from Jolla's guide and an also necessary pkcon refresh, which some seem to omit when upgrading manually at the command line (often running into aforementioned issues later, then).
  • sfos-upgrade's source files are hosted at Github.
  • For discussing its specific scripts and RPM packaging, please use its issue tracker at Github.
  • Issues with this RPM package or the shell scripts it installs shall also be filed at sfos-upgrade's issue tracker at Github.


Application versions: 
File sfos-upgrade-1.2-1.noarch.rpm10.78 KB17/02/2019 - 17:53
File sfos-upgrade-2.1-2.noarch.rpm11.53 KB02/03/2019 - 19:55
File sfos-upgrade-2.2-1.noarch.rpm11.68 KB04/03/2019 - 16:42
File sfos-upgrade-2.3-1.noarch.rpm11.7 KB10/03/2019 - 16:21
File sfos-upgrade-2.4-1.noarch.rpm11.71 KB17/03/2019 - 17:09
File sfos-upgrade-2.5-1.noarch.rpm11.87 KB19/04/2019 - 16:51
File sfos-upgrade-2.6-1.noarch.rpm11.89 KB28/04/2019 - 16:54
File sfos-upgrade-2.9-1.noarch.rpm12.05 KB26/05/2019 - 12:06
File sfos-upgrade-3.1-4.noarch.rpm14.32 KB04/07/2019 - 19:45
File sfos-upgrade-3.2-3.noarch.rpm14.41 KB03/10/2019 - 23:15
File sfos-upgrade-3.5-6.noarch.rpm15.56 KB12/12/2019 - 02:34
File sfos-upgrade-3.6.3-stable3.noarch.rpm26.6 KB25/01/2020 - 17:46
File sfos-upgrade-3.7.8-stable12.noarch.rpm27.93 KB19/10/2020 - 18:09
File sfos-upgrade-3.8.2-stable15.noarch.rpm28.24 KB16/05/2021 - 13:52
File sfos-upgrade-3.8.4-stable17.noarch.rpm28.79 KB21/09/2021 - 23:17
File sfos-upgrade-3.8.5-stable18.noarch.rpm28.68 KB01/10/2021 - 13:30


PawelSpoon's picture

Are you suggesting to.disable all repos in storeman ? Or at least those that might have "bad" content?

olf's picture

Well, the way I try to avoid issues with repositories, which offer RPMs replacing system RPMs, is to not enable them.  As soon as I become aware of such a "replacing RPM" in a repository I have enabled, I disable it.  As this issue only hit (past tense, see below), when upgrading SailfishOS, this strategy has saved me from mishaps of this kind.

If you want to install an RPM from such a repository, download that RPM from OpenRepos and install it per pkcon install-local.  But then you have to notice updates of this RPM and install them the same way (i.e., both 100% manually).

An exception can be the few single-purpose repositories, which are created due to this issue: They offer a single (set of) "replacing RPM(s)" (often in multiple versions), and exist for separating these critical RPMs from the authors main repository.  Their authors usually denote, if that specific repository can be left enabled when upgrading SailfishOS (e.g., for obexd-contentfilter-off) or not.

But it was really difficult for users to identify repositories, which offer RPMs replacing system RPMs: While this may be discussed in depth for the "replacing RPM" in that repository, a user may have enabled that repository for installing a different RPM and may never take notice.

Since SailfishOS 3.4.0 though, when you are upgrading SailfishOS at the GUI, you are interactively queried, if you want to uninstall RPMs, which replaced system RPMs on your SailfishOS installation.  This makes it easy to backtrack the enabled repositories, which offer RPMs replacing system RPMs.  Side note #1: AFAIU, one can abort after this check, before performing the upgrade proper at the GUI. Edit: Not sure, after having done that once, because (as of SFOS 3.4.0) the UI is minimalistic, not self-explanatory, and without feedback what is done.  Side note #2: Note that this mechanism also disables the repositories where these RPMs were installed from! (That made me filing a false bug for Storeman.)
Then you can decide (taking above information into account), which repositories to disable before upgrading SailfishOS, and which to leave enabled.

PawelSpoon's picture

Hi olf,

i am running the upgrade for the first time, during that it seems that also the installed apps do get updated. is that true and wanted ?

Best Regards


olf's picture

Please see the first bullet point of the "Notes" in sfos-upgrade's description above.
P.S. (edit):

  • Only Jolla's GUI updater performs something, which Jolla calls "repository separation" (IIRC since SFOS 1.0.4 and refined in some 1.1.x), and which does not fully work (I think you recognise the pattern):
    All RPMs from active non-Jolla repositories, which substitute RPMs from Jolla's repositories, are still updated during an SFOS upgrade, plus (much worse) these are unconditionally installed (as updates to Jolla's RPMs) when upgrading SFOS.
  • All methods of upgrading SFOS show this behaviour. The GUI updater only tries to prevent some ways of breaking SFOS during an upgrade; which ones is unknown, as these tools are proprietary, but this case is definitely not covered (it may be covered since SFOS 3.4.0).
    So take care not to have community repositories enabled during an SFOS upgrade, which offer replacements for Jolla's RPMs, but you have not installed (all) these replacement RPMs, yet (because without disabling such an community repository before upgrading SFOS, you will, after upgrading).
PawelSpoon's picture

@PamNor, you need.to make place, a lot place. Then balance . Try to get rid of 30%, else balancer will not work properly. Value of 68 was a good value as far as i remember

PamNor's picture

That's for tips, but same problem. I agree. It's not a SFOS-UPGRADE problem but a btrfs allocation problem. Thanks anyway for your support.

PamNor's picture

Running btrfs-balancer allocation and balance both gives error: "Failed to get allocation". Lipstick not starting, but I can loggin with ssh. Prefer not to restore this Jolla1.

olf's picture

This is completely unrelated to sfos-upgrade.
Plus IIRC, this was already answered at TJC!

Nevertheless, try using the basic btrfs commands, specifically btrfs balance, e.g. starting with btrfs balance start -d usage=0.
If this is successful, use btrfs-balancer then.

martonmiklos's picture

Hello Olf,

I would suggest you to change the Changelog description here at openrepos to cover all characters with the link. I have implemented in the Storeman that it opens up automatically the changelog link if it contains "mainly an url" see:


However the ratio between the non-link and link texts in the current "A coarse changelog is provided per release comments at Github." is over the single link detection threshold to being able to redirected by the app directly.

olf's picture

@martonmiklos, it does not work as (you) promised, despite the single link's text now covers all characters of the changelog field except for three. :(

olf's picture

Ack & done.

direc85's picture

Thank you for this tool! It hasn't saved my bum yet, but it lets me see what's happening in the background! I wish I had used it when my XA2 borked the update, but I did it normally via the graphical method...

Psst! You can use `sfos-upgrade "$(version | grep -o '[0-9.]*')"` for the 'samegrade' command, it's a lot easier to type! No you can't because of Inoi R7 version string format... (In the series of "Things I learned today": SFOS uses BusyBox `grep` which does not support `-E` flag.)

Edit 1: Aww what the heck. Please see my PR; I implemented "--verify" parameter to skip that altogether.

Edit 2: Inoi R7 version string format.

olf's picture

Many thanks for the idea and PR: merged

scanner's picture

SailfishOS (Lapuanjoki)

ssu re
WARNING: ssu.ini does not seem to be writable. Setting values might not work.
Device release is currently:

ssu s
WARNING: ssu.ini does not seem to be writable. Setting values might not work.
Device registration status: not registered
Device model: Intex Aqua Fish (l500d / Aqua Fish)
Device UID: ***
Domain: sales

olf's picture

Thank you!

So sfos-upgrade should already work fine on Intex Aqua Fishs.

Reading related articles about the status of support for the Aqua Fish at TJC [1], [2], [3], [4], the last well running SailfishOS release for original Aqua Fishs (i.e., not converted to Jolla C) is
One may be able to upgrade to SFOS 3.0.0, but not any further without breaking things, and 3.0.0 brought many changes, among them a couple of flaws (most being fixed in later releases).
BTW, this may also be of interest.

olf's picture

BTW, sfos-upgrade is in "maintenance mode" since version 3.6, as it appears to be working well for its users. That means there will be no new releases, unless bugs are reported (preferably at Github) or a new SailfishOS release breaks it.

P.S.: Still it would be helpful if owners of an Inoi T8, Jala Accione or Jala Accione P contribute the output of version, ssu re and ssu s on their devices to issue 32.

olf's picture

If you own a device sold by Inoi (e.g. R7 or T8), Jala (Accione or Accione P) or Intex (Aquafish, not reflashed as Jolla C), please consider contributing information to issue 32, at least the output of version, ssu re and ssu s.

olf's picture

Meanwhile @ItsHardToTakeUsername was so kind to provide this information for an Inoi R7, still it would be very helpful if owners of an Inoi T8, Jala (Accione or Accione P) or Intex (Aquafish, not reflashed as Jolla C) contribute the output of version, ssu re and ssu s on their devices to issue 32 (or here).

anasyntes's picture

Thank you! Much appreciated.

dalas_revo's picture

Thanks for the scripts, I use them on my XA2. Unfortunately upgrading from to on the Aigo (Jolla Tablet) fails for me with sfos-upgrade, complaining about a missing /sys/class/power_supply/battery/uevent.

olf's picture

@dalas_revo, please let us analyse this at Github's issue tracker: I opened an issue there with questions for you and "might introduce an override for this after some more analysis".

olf's picture

A proper solution for this (now also extracting the battery information on Aigo tablets and other devices with unusual battery paths) was implemented in the v3.1 pre-release.
One may download it from Github and manually install it (or per Storeman -> Local RPM files).
Feedback at Github for this or other functionality is appreciated, as always.

oxygenh's picture

I have same issue, that SrDweeb. Sfos-upgrade report abour DOWNGRADE when i try to from

olf's picture

Can confirm that sfos-upgrade incorrectly warns about downgrading, when upgrading from SailfishOS 3.0.3.x to
This is solely an usability issue, simply answer with y or Y when asked if you really want to perform the "downgrade", then sfos-upgrade will upgrade SailfishOS as usual.
This will be rectified in the 3.0 release.

oxygenh's picture

Thank you very much.

olf's picture

See issue #24 for details and a fix.

DrDweeb's picture

Upgrade from to sends a downgrade warning, suggesting you have a problem dealing with 2 digit point upgrades - an embarrassing oversight

DrDweeb's picture

Thanks, sadly I must manually install every time so this is fabulous!

Maximilian1st's picture

Just wanted to say thanks for the scripts, for some reason the only way for me to update an Xperia X 5122.

seiichiro0185's picture

Thanks for this nice script, upgrade on XA2 Plus from to worked without problem.