Your rating: None Average: 5 (47 votes)

Scripts for fail-safe and semi-automated upgrading of SailfishOS at the command line with logging

Upgrading SailfishOS at the GUI (via 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 semi-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 2 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 to this SailfishOS version. 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 (by e.g. ssu re <version>) before executing sfos-upgrade without a parameter.
  • sfos-upgrade --verify
    Performs a "samegrade" operation, i.e. checks if the recent versions of all available 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.
    When upgrading to SailfishOS releases < 4.1.0, you may omit running `post_sfos-upgrade` between consecutive SailfishOS upgrades (but do reboot each time!).  But you shall run it after having upgraded to any SailfishOS release ≥ 4.1.0 or the ultimately 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-3.9.22-release14.noarch.rpm30.59 KB21/03/2023 - 17:28
File sfos-upgrade-3.10.1-release2.noarch.rpm30.87 KB21/03/2023 - 17:28
File sfos-upgrade-3.11.2-release2.noarch.rpm21.42 KB27/09/2023 - 04:30
File sfos-upgrade-3.11.3-release3.noarch.rpm21.8 KB08/03/2024 - 02:03


objectifnul's picture

Is this app suitable for SFos 4.5x upgrade? Release notes aren't 100% clear on this question.

olf's picture

The way I read the release notes for SailfIshOS 4.5.0, they transport Jolla's usual mantra, which has been stated a couple of times before: Only upgrade SailfishOS at the command line, if Jolla's GUI updater fails.

Jolla's guide for upgrading SailfishOS at the command line is unchangend, so sfos-upgrade still does that correctly.

Seven_of_nine's picture

Works like a charm, thank you so much!

jolla4ever's picture

Anyhow, I tested

sfos-upgrade --verify

followed by


Worked like a charm! Thank you!

olf's picture

Thank you for testing.

Yes, that (--verify) is all you can test, when you already upgraded to the most recent SailfishOS release; but using the "--verify"-option is also fully sufficient to re-test issue #71.

And also a "Yes" for the statement, that one should not try to downgrade SailfishOS*, unless that specific SFOS installation is already broken in a way, which can only be fixed by a downgrade: Then you may try to downgrade (as a last resort measure), but this usually fails (with an error message) or messes up this SFOS installation even further.  Hence often one has to resort to re-flashing SailfishOS then, OTOH one might try to downgrade first, consequently: If that fails, re-flash.

*: Downgrading to a lower point release (last field of the four version fields of SaillfishOS) seems to work fine, as someone reported somewhere.

jolla4ever's picture

Very nice that you responded so quickly to this post. Indeed this has been previously reported by @nephros on GitHub, I didn't know that. I would like to test your modified version. However, I have already performed the update in the regular way. And downgrading does not seem to be possible: https://jolla.zendesk.com/hc/en-us/articles/201836347#6

jolla4ever's picture

I tried upgrading Xperia iii from to Nothing happened.

olf's picture

Thank you for reporting.

This is a duplicate of issue #71 at GitHub, see there for further details and a pre-release of a fixed version.
Please test and report success or failure here or at GitHub.

naytsyrhc's picture

I am unable to upgrade to

[root@gismoii defaultuser]# sfos-upgrade
/usr/bin/sfos-upgrade: line 177: final_sfos_releases: parameter not set
/usr/bin/sfos-upgrade: line 196: final_sfos_releases: parameter not set

olf's picture

…, because you are using an outdated version ≤ 3.9.4!

naytsyrhc's picture

But there are no updates? (I have chum installed as well, but it doesn't provide updates either)?

olf's picture

Reading (two comments below) helps: https://openrepos.net/comment/40691#comment-40691
⇒ Remove ("uninstall") sfos-upgrade and install it again, for example with Storeman.

P.S.: sfos-upgrade has not been submitted to the SailfishOS:Chum repository (yet).  You can do that at any time, if you want sfos-upgrade there.

naytsyrhc's picture

Uh. Well, sorry. Did not read that. Obviously.

hss's picture

Storeman does not let me update or even say there is an update. I can uninstall and install again to get the new version but I'm curious why this is happening. Any ideas?

olf's picture

Yes, I omitted setting the vendor in the RPM spec file for v3.9.4 and v3.9.5, which constitutes a vendor change (from "olf" to ""), as I found out later.  Because this blocks the update path, I reverted the vendor to "olf" for v3.9.6 (which in turn blocks the update path for v3.9.4 & v3.9.5) and deleted v3.9.4 & v3.9.5.

For details, see https://en.opensuse.org/SDB:Vendor_change_update

direc85's picture

As I was upgrading to 4.3 EA today, I was struggling with free space on root partition. I managed to free up space, but only after I remembered that I had plenty of debuginfo and debugsource packages installed (about 1GB of worth, 25% of partition size). That gave me an idea that sfos-upgrade could hint the user that such packages are installed and removing them could free up noticable amount of space. How that idea sounds?

olf's picture

Well, to provide the user with something more specific than "free up some space by cleaning up or enlarging the root partition" sure would be nice.
But I am afraid that everybody clutters their root volume in a different way, some just by using the original root volume size and installing some native software, some by installing lots of software on an enlarged root volume, some with some files erroneously backed up somewhere on the root volume etc. etc.  Thus I have no idea what to look for: The "space eaters" can be of any file type or name extension, and comprised of many small files or a few big files.

But it is sure O.K. to look for a single or few specific pattern(s), as long as that does not result in false positives and / or a significantly extended run-time (mind that the find utility may take a while, if its search is broadly specified).

So it might make sense to check how much space the installed debuginfo and debugsource packages are using on the root partition, when space there is scarce.

As you know, I am always open to consider and discuss pull requests at https://github.com/Olf0/sfos-upgrade and your question has triggered me to activate the GitHub-discussion feature there.

Besides a technical approach, enhancing the text output with more specific guideance how to determine "space eaters" might make sense and may even be sufficient.  Unfortunately ncdu is not available in Jolla's repositories, but IIRC some graphical utility at Openrepos exists to look for "space eaters": Do you remember its name or have other suggestions for utilities a simple user can use for this purpose (i.e., not find)? Space Inspector by Arno Dekker (ade), originally by Jens Klingen.

Please open a discussion thread or pose a PR at https://github.com/Olf0/sfos-upgrade, and drop its link here (in a reply to this message), so other interested people can follow and chime in to further discussion.

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