Upgrade to a newer postmarketOS release

From postmarketOS

Upgrading from one postmarketOS release to the next one is supported since v22.06 was released, meaning from v21.12 to v22.06 is the first supported upgrade. Upgrading from the latest stable version (v23.12 as of 2023-12-18) to edge is also supported. In theory, postmarketos-release-upgrade is capable of upgrading (or even downgrading) from any postmarketOS version to any other. But for the supported upgrades we have a daily running CI check that ensures the most commonly used UIs can be upgraded without errors.

Preparation

The upgrade steps will be done through the terminal. Using a separate computer and connecting to your phone over SSH is recommended, so you still have control even if the UI becomes unresponsive. Running tmux or screen is also recommended, so the upgrade does not stop in case the SSH connection breaks. Consider creating a backup if you have anything important on your device. Make sure you have a stable internet connection when attempting to upgrade.

Install postmarketos-release-upgrade:

# apk add postmarketos-release-upgrade

If you are on a postmarketOS release older than v21.12, the script is not packaged. Grab it directly from the git repository, it has no dependencies.

$ wget https://gitlab.com/postmarketOS/postmarketos-release-upgrade/-/raw/master/upgrade.sh
$ chmod +x upgrade.sh

Run the script

Once you run the script, it will ask if you want to upgrade to the latest stable release by default and explain exactly what it is about to do.

# postmarketos-release-upgrade
>>> You are about to upgrade from v21.12 to v22.06.
>>> 
>>> This will be done in the following steps:
>>> 1) upgrade packages of v21.12
>>> 2) dry run: upgrade packages to v22.06
>>> 3) upgrade packages to v22.06
>>> 4) prompt to reboot
>>> 
>>> A log and backup of your /etc/apk/repositories will be in:
>>> /var/lib/postmarketos-release-upgrade/2022-06-12-122502
>>> 
>>> It is strongly recommended to do this via SSH and in tmux/screen.
>>> More information: https://postmarketos.org/upgrade
>>> 
>>> This upgrade should work fine, but in the worst case your device
>>> may not boot anymore. Make backups of important data first!
>>> 
>>> Proceed with upgrade to v22.06? [y/N]

If you want to upgrade to another channel, pass it as argument as shown in the help output.

# postmarketos-release-upgrade -h
usage: postmarketos-release-upgrade [-h] [CHANNEL]

arguments:
  -h       show this help
  CHANNEL  the release channel to upgrade/downgrade to, e.g.
           "v22.06" (default) or "edge"

CHANNEL must be set if you are already on edge.

Rebooting

When it's done, you are asked to confirm the reboot:

>>> (4/4) Reboot prompt
>>> 
>>> Your system is in a weird state between v21.12 and v22.06 now.
>>> All bugs are features until rebooted. If you know what you are
>>> doing and don't want to reboot, press ^C.
>>> 
>>> Press return when you are ready to reboot.

Troubleshooting

If the upgrade failed and you don't know what to do, consider joining the chat to ask for help. Keep in mind that this is not a paid support contract, there are just some nice people who may help you out in their spare time.

If the script fails before step 3 (upgrade packages to new release), your /etc/apk/repositories will still be configured for the old release. Read the log to figure out why it failed. Possibly running apk fix helps to resolve simple packaging errors. You are still on the old release in that scenario, and should be able to use it just like before trying to upgrade.

If the script fails during step 3, the /etc/apk/repositories will be configured for the new release. Try to run the upgrade command manually (apk upgrade -a), maybe it passes now (e.g. if your internet was disconnected). Running apk fix may also help.

Note that the old /etc/apk/repositories file is backed up in /var/lib/postmarketos-release-upgrade/ along with a log of the upgrade. If you know what you are doing, you can use this to restore the old file.

If the failure was caused by a bug in the script, please look for an existing bug report, extend it if it makes sense or if you can't find one, open a new bug report and attach the log. The bugs of postmarketos-release-upgrade are tracked here. The script is a simple shell script, consider trying to fix it yourself and submitting a patch.

See also