While Docker has been my go-to for isolated experimentation without affecting my laptop’s setup for a while now, today I needed a device with its own browser to test both on and off the local network. I realised I still had a Raspberry Pi tucked away in a cupboard — a perfect candidate for the job, though likely very outdated.

Sure enough, it was online and running Raspbian OS Stretch from 2017, which lost support in early 2024. The pre-installed Chromium browser was so old that some sites even blocked it… no problem, I thought — I’d just install the latest Firefox. But soon, apt threw errors about incorrect entries in sources.list preventing package upgrades and installs, and I found myself down a rabbit hole. I couldn’t immediately find a coherent guide for upgrading from Stretch, so I decided to document my journey here for anyone else facing the same issue.

Thankfully in my case, this thing was not internet facing, but it was on the local network and could have provided a useful entry for someone with a certain set of skills.

Wait, why not just perform a fresh install?

#

If you’re ready to jump straight to Bookworm, the best approach is to perform a clean install. This avoids potential complications from upgrading across multiple OS versions and ensures your system is running as smoothly and efficiently as possible.

However, the Raspberry Pi was designed for experimentation, modding, tinkering and tweaking. Chances are, there’s bits and pieces all over the place that are probably not worth the effort of finding and backing up one at a time, but might worth keeping. If you don’t care about this stuff, you can just leap ahead and install from fresh in a fraction of the time it takes to manually upgrade one major version at a time. While this is the cleanest and most straight-forward option to get your device up to date, it might not suit everyone; especially if you’ve spent a long time on a specific configuration or setup.

To install a fresh version and wipe the slate clean

#

1. Download the Latest OS Image: Head over to the Raspberry Pi website and download the Raspberry Pi OS Bookworm image.
2. Flash the Image: Use an imaging tool like Raspberry Pi Imager or Balena Etcher to write the OS image to your SD card.
3. Boot from SD Card: Insert the SD card into your Pi and power it on to boot into your new OS.

The remainder of this article explains the process on how to manually upgrade Raspberry OS to the latest version.

Checking Hardware Compatibility

#

My first thought for upgrading the OS to latest for such an old machine would be to check if the hardware can support it. It’s possible to find the model of the Raspberry Pi by using the following command:

cat /sys/firmware/devicetree/base/model && echo

Fortunately though, this ended up being totally moot, because Raspberry Pi OS remains to be compatible with all Raspberry Pi models.…Nice!

May long this continue!

How to Upgrade from Raspberry Pi OS Stretch to Bookworm

#

Raspberry Pi OS Stretch has been around since 2017, and it’s understandably showing its age a little bit. Over the years, several major versions of Raspberry Pi OS have been released, offering security improvements, features, and optimisations that make upgrading well worth doing.

Here’s a table summarising the release dates and support windows for recent Raspberry Pi OS versions:

Staying up-to-date is essential for optimising performance and longevity of the Pi — particularly if you’re using it for projects that need security, like home automation, remote access, or advert blocking with Pi-hole etc.

Raspberry Pi OS doesn’t support direct upgrades from Stretch to Bookworm, so we need to perform incremental upgrades through each intermediate version: Stretch to Buster -> Buster to Bullseye -> Bullseye to Bookworm. I’m not sure it’s even possible without instead performing a fresh install, but skipping versions would most likely cause compatibility issues with packages and dependencies. Each OS iteration will bring changes to the kernel, system libraries, and software repositories that must be applied step-by-step.

Toy Story: A naming convention

#

While writing this article, a quirky detail about Raspberry Pi OS names suddenly hit me: they’re all named after characters from the Toy Story films. For instance, Stretch was the purple octopus from Toy Story 3, Buster is Andy’s dachshund, Bullseye is Woody’s loyal steed, and Bookworm is the spectacled book lover also seen in Toy Story 3. Perhaps everyone knows this, but it was certainly news to me. Anyway - let’s get to work!

Before You Begin: Make a Full Backup

#

As always with things like this - it’s absolutely crucial to create a backup of your data. This includes not only your important files (sometimes easier said than done) but a full backup of the whole SD card. If something goes wrong during the upgrade, having an SD card backup means you can restore your system to where we started. Tools like Raspberry Pi Imager, Win32DiskImager, or Balena Etcher work well for creating a full SD card image, allowing you to preserve all your data and system configurations.

Important Note: This Process Takes Time

#

Upgrading the OS in the manor as follows takes a fair amount of time — often a couple of hours per version hop. If you’re connected over SSH from your laptop or any other device that could potentially go to sleep, consider using the screen utility on the Raspberry Pi. This allows you to run the upgrade commands in a detachable session, allowing you get on with other things; Watching a gazillion lines of logs for hours probably isn’t the best use of your time.

To install and use screen:

sudo apt install screen
screen

You can detach from a session with Ctrl + A and then D. To reconnect, use:

screen -r

I strongly recommend experimenting with screen before using it in anger; specifically with detaching and reattaching. It can come across a bit fiddly to new users, but once you get the hang of it, it’s a super useful tool for system administration. See screen’s man page or view the manual here.

In-Place Upgrade from Stretch to Bookworm

#

For those looking to keep their current setup and files intact, here’s a guide to performing an in-place upgrade from Stretch to Bookworm. Again, be aware that this method carries some risk, so it’s strongly recommended to have a recent backup.

1. Prepare for Upgrade

#

Fully update your current OS packages before starting the upgrade:

sudo apt update
sudo apt full-upgrade

2. Upgrade Stretch to Buster

#

2.1. Edit Sources Files
Update the following files by changing stretch to buster:

• /etc/apt/sources.list
• /etc/apt/sources.list.d/raspi.list

For example, in /etc/apt/sources.list:

deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi

And in /etc/apt/sources.list.d/raspi.list

deb http://archive.raspberrypi.org/debian/ buster main

Tip 🚀 - Use sed to update your list files

#

To change the release name in both files, you can use sed to replace stretch with buster in a single command:

sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list /etc/apt/sources.list.d/raspi.list

Obviously you can rinse and repeat with the other versions in upcoming steps.

Heads up: I hit this issue at this stage.

2.2. Run the upgrade

sudo apt update
sudo apt full-upgrade -y

Warning: The -y flag automatically accepts all prompts during the upgrade process, which is convenient for most users. However, if you prefer to review and confirm each change, run sudo apt full-upgrade without -y to make those choices manually.

2.3. Reboot

sudo reboot

3. Upgrade Buster to Bullseye

#

3.1. Update the sources files again, replacing buster with bullseye

/etc/apt/sources.list

deb http://raspbian.raspberrypi.org/raspbian/ bullseye main contrib non-free rpi

/etc/apt/sources.list.d/raspi.list

deb http://archive.raspberrypi.org/debian/ bullseye main

To quickly update both files:

sudo sed -i 's/buster/bullseye/g' /etc/apt/sources.list /etc/apt/sources.list.d/raspi.list

3.2. Run the upgrade

sudo apt update
sudo apt full-upgrade -y

Heads up: I hit this issue at this stage.

3.3. Reboot again:

sudo reboot

4. Upgrade Bullseye to Bookworm

#

4.1. Update the sources files, now replacing bullseye with bookworm

/etc/apt/sources.list

deb http://raspbian.raspberrypi.org/raspbian/ bookworm main contrib non-free rpi

/etc/apt/sources.list.d/raspi.list

deb http://archive.raspberrypi.org/debian/ bookworm main

Quickly update both files:

sudo sed -i 's/bullseye/bookworm/g' /etc/apt/sources.list /etc/apt/sources.list.d/raspi.list

4.2. Run the upgrade

sudo apt update
sudo apt full-upgrade -y

4.3. Reboot:

sudo reboot

5. Final System Check

#

After the upgrade, remove any obsolete or deprecated packages to keep your system clean and optimised:

sudo apt autoremove
sudo apt autoclean

Troubleshooting

#

Deprecated Components: The ui Warning

#

When upgrading from older versions like Stretch, you may see a warning related to a deprecated ui component in your sources list. The ui component was initially part of earlier Raspberry Pi OS repositories, providing packages related to the user interface, but it’s been deprecated and removed in recent versions (like Bullseye and Bookworm). If ui remains in your sources list, you may see warnings similar to the following during apt update:

W: Skipping acquire of configured file 'ui/binary-armhf/Packages' as repository 'http://archive.raspberrypi.org/debian bullseye InRelease' doesn't have the component 'ui' (component misspelt in sources.list?)

To resolve this, simply remove ui from /etc/apt/sources.list.d/raspi.list.

1. Open /etc/apt/sources.list.d/raspi.list:

   sudo vi /etc/apt/sources.list.d/raspi.list
   

2. Remove ui from any lines that include it, such as:

   deb http://archive.raspberrypi.org/debian bullseye main ui
   

   Change it to:

   deb http://archive.raspberrypi.org/debian bullseye main
   

3. Save the file and run sudo apt update again to confirm the warning is gone.

Removing this deprecated component will allow the upgrade to proceed without warnings and prevent potential conflicts with newer package sources.

‘No space left on device’ error

#

As part of this journey, a lot of packages will get cached and you might even run out of space in the root disk. If this happens, you’ll need to clear up some junk files and re-run the command that failed. Be sure to take a look at my article on this topic Reclaiming space on Linux Machines if you need any guidance in this area. There’s a bunch of tips and tricks about reclaiming space on your linux devices.

Held Packages

#

There may be cases of incompatible versions of essential packages (like libc6-dev and libgcc-8-dev) during an upgrade. This typically happens because of “held” packages, where some packages are “pinned” to an older version, preventing dependencies from properly resolving.

If you run into these issues;

1. Check for Held Packages

#

Check for packages that are currently held:

sudo apt-mark showhold

If there are any packages listed, un-hold them so they can be upgraded like so:

sudo apt-mark unhold <package_name>

For example:

sudo apt-mark unhold libc6-dev libgcc-8-dev

2. Update and Try the Upgrade Again

#

Run the following commands to make sure all package information is up-to-date and then try upgrading again:

sudo apt update
sudo apt upgrade --fix-broken
sudo apt full-upgrade -y

3. Manually Install Dependencies

#

If the issue persists, you may need to manually install the required versions of the dependencies:

sudo apt install libc6-dev libgcc-8-dev -y

4. Clean Up Package Cache

#

If there are still issues, clearing the package cache can help ensure no outdated packages are causing conflicts:

sudo apt clean
sudo apt autoclean
sudo apt autoremove

Then, try updating and upgrading again:

sudo apt update
sudo apt full-upgrade -y

5. Use dist-upgrade as a Last Resort

#

If the issue remains, try using dist-upgrade, which may resolve complex dependencies:

sudo apt dist-upgrade -y

6. If you’re still seeing issues…

#

Uninstalling problematic packages may be the only way forward. Start with the least critical, one at a time, whilst retrying the full-upgrade. Be careful with core packages as uninstalling them (such as libc6-dev) could brick your machine. If you’ve taken a backup you can always go back anyway, but you have been warned!

After resolving the dependency issues, proceed with the usual upgrade steps and reboot as necessary as seen earlier in this article.

Wrap Up

#

Upgrading your Raspberry Pi OS over several major versions is no small task. By following this guide, you’ve taken your Pi from an older, unsupported OS through several major upgrades, making it up-to-date and secure for future projects.

Keeping your Pi updated maximises its performance, security, and compatibility, which is especially valuable if you’re running long-term projects or experimenting with new applications. Whether you chose the clean install route or tackled the in-place upgrade, you’ve set yourself up for a more powerful and future-ready Pi.

If you have any questions or thoughts, feel free to drop a comment below!