Upgrading Alpine Linux to a new release branch

This page covers upgrading Alpine Linux to a newer release branch. To apply regular security updates and bugfixes refer Upgrading a running system. 
== Upgrading to latest release ==
When Alpine Linux is installed in sys mode, e.g. on a hard drive, upgrading to the next stable version involves 3 steps
# Update Repositories file 
# Updating package lists
# Upgrading packages
i.e Updating the file followed by a straightforward package manager operation. However, for older release branches, refer Upgrading from older versions for specific upgrade steps. 
== Upgrading to Edge ==
== Downgrading from edge ==
To downgrade from Edge, modify the repositories file as explained in Upgrading to latest release, then run the following commands:
This will usually downgrade all packages automatically, but do not be surprised if you need to manually remove and reinstall a package to complete these commands.
== Upgrading Alpine Linux on CD ==
=== Boot media === 
If the boot media being used (such as a CD, for example) is separate from the media used to store the configuration information, simply download the latest ISO, and replace the boot media contents with the contents of the latest ISO.
If booting from a CD, this would simply mean replacing the CD with a CD made from the new image and rebooting the Alpine Linux box. 
== Update local package installations ==
If you have locally installed and configured additional packages using APK caching you should also perform the following steps.
Backup the local configuration prior to upgrading.
Update your repositories using the procedures detailed above.
After upgrading the packages, save the upgraded configuration changes, before rebooting the system.
== Upgrading Alpine Linux on other removable media (such as CF/USB) ==
The following instructions are for run-from-RAM Alpine installations running on Compact Flash or USB media. Updating your repositories using the procedures detailed above, then running:
will suffice for some purposes. (If you want the new packages to be used after a reboot, you should enable APK caching.)
However, this is not an adequate general solution because it won't honor any kernel upgrades and the like. For the general solution, you'll need to upgrade your boot medium (Compact Flash or USB). That is what the following steps describe how to do.
=== Upgrade Operating System ===
Start by checking that you have enough space on your media. For a standard Alpine image, you need at least 400MB available space.
==== Download and verify new release ====
Make sure the media that holds your Alpine system is mounted readwrite.
If using Alpine Linux 2.2.3 or newer: Download the latest release, and then use the following command to mount and copy files as needed for you: 
=== Save changes ===
Now that all upgrades are done, we should save our settings to our media (which you hopefully have backed up prior to doing this upgrade).
=== Load new kernel ===
In most cases you will need to reboot Alpine Linux (especially if there are changes in the kernel):
=== Update to latest kernel on armhf (eg. Raspberry Pi 0 or 1) ===
On Alpine 3.X and newer, kernel is not upgraded when using apk upgrade and setup-bootable does not work properly.
If you want to upgrade your kernel, you will need to get it from the latest release, but first you must have and run :
So now all your packages are upgraded, you can upgrade your kernel.
1. We need to get some variables :
2. You must verify if they are correctly set, using this :
3. And it will output something like this (if not, do not continue this process) :
4. Then you can run this script (WARNING : config.txt will be overwritten!) :
5. Test-it !
Alternatively, you may upgrade the kernel from repositories.
=== Update local package installations ===
This is done just as at #Update local package installations, above.
== Updating a USB/CF diskless install without setup-bootable ==
It is possible to update a diskless install of Alpine from another system, or without using the setup-bootable script. This was tested for the 3.13 to the 3.14 upgrade on a Raspberry Pi.
Before starting, update /etc/apk/repositories file to retrieve packages for the new release. Then update all packages with:
We can then use update-conf to check for changes to configurations from the new packages.
We now need to prepare to update the kernel and boot materials. To do this, we stop the modloop (which is the loopback mount providing kernel modules) and remount the SD media as read/write.
We can also shutdown the system, eject the media, and perform the next steps on another machine (if so, skip this command block)
At this point, remove all files from the SD media except for /cache, *.apkvol.tar.gz, usercfg.txt, and config.txt Rename config.txt to config.txt.bak temporarily, as extracting the new tar file will overwrite the file.
We can now download the new release and extract it. This example is for an Alpine Raspberry Pi release, so feel free to adjust the URLs for your system. 
Restore the original config.txt:
Update the persistent storage using lbu:
We can now reboot, and this should boot into the new kernel. Once this is done, we can clean up and re-download apk caches:
Category:Installation
Category:Package Manager