Upgrade to a newer postmarketOS release

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 (v24.06) 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

Update the package repositories:

# apk update

Warning: if you have a space-constrained device, read this content. Prior to the upgrade, check available space, or at least use the upgrade -s (simulate, or dry-run) flag to display how "large" the upgrade is. This recommendation is not limited solely to new release upgrades. There are two factors involved: space required to download (cache) packages, and additional space required after the packages are installed. Upgrade provides neither of these values (contrast with apk add). Upgrade is an all-or-nothing event, where anything short of all is problematic. Perform an apk cache clean and / or apk cache purge to recover space. Save a backup of all packages installed on the system. If necessary, manually decompose the single upgrade into several incomplete upgrades by explicitly listing packages to be upgraded. Use the --prune flag. Between each partial upgrade clean or purge as necessary. If it appears that the full upgrade cannot be completed within space constraints, it may be possible to revert to the previous packages (untested). Otherwise, the only outcome to be expected is the warning and fatal error unable to cache: No space left on device; the device will almost certainly be left in an unbootable state.

Upgrade installed packages (all available; or [space-constrained] sequence of incomplete upgrades):

# apk upgrade --available
# apk upgrade package1 package2 ...

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.postmarketos.org/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]

Upgrade to another channel

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.

For example, to switch to the "edge" channel:

# postmarketos-release-upgrade 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.

Preparation

Run the script

Upgrade to another channel

Rebooting

Troubleshooting

See also