How to Upgrade Raspberry Pi OS from Bullseye to Bookworm

The new Raspberry Pi OS version (codename “Bookworm”) is now officially available. While it’s recommended to install a fresh new version, it’s still possible to try an upgrade on non-critical systems. Let’s discuss your options there.

As a general rule, it’s always risky to try an upgrade from one major version to the next without reinstalling. Knowing this, it’s still possible to do it, by updating the sources.list file of the APT package manager.

I’ve tried it, and I can share my experience with you in this article. Let’s first discuss why it’s not recommended, and then see how to do it if you are not too worried about the results.

If you’re looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Should you upgrade Raspberry Pi OS from Bullseye to Bookworm?

Do you really need to upgrade to Bookworm?

While progressively migrating your Raspberry Pi devices to Bookworm is a good idea, upgrading them directly from an older version to the latest one is not recommended, and probably not even necessary.

Debian and the Raspberry Pi Foundation will continue releasing security updates for your devices running on Bullseye for a while (at least for as long as it’s available as a “Legacy” option in Raspberry Pi Imager).

So, there is no rush. You have the time to install a clean new version on a new SD card or SSD drive, and migrate your applications there step-by-step.

With the release of the Raspberry Pi 5, it’s probably a good idea to get this brand-new model to replace your existing setup, install Bookworm on it, and migrate your applications progressively.

General rule

The general rule, when a new Debian or Raspberry Pi OS version is released, is to install it from scratch, then add the applications, and migrate the configuration and data from the previous system. This is the recommended way to do it.

It doesn’t mean you can’t upgrade directly, it is just the safest way to do it. It allows you to go slowly, test, and make sure everything is OK.

When I was a system administrator, I did a major upgrade several times on Debian servers, and it worked pretty well. You have to be willing to deal with bugs depending on the applications you use, but sometimes it’s easier than having a long downtime.

So I know there can be a difference between the “good practice” and what you’ll really do.

Anyway, in this case, the Raspberry Pi Foundation clearly discourages us from trying it. There are many changes in the background (display, audio and network management), that make this procedure even more risky than usual.

[…] because the changes to the underlying architecture are so significant, we are not suggesting any procedure for upgrading a Bullseye image to Bookworm; any attempt to do this will almost certainly end up with a non-booting desktop and data loss.

Simon Long – Software Engineer / Raspberry Pi

My advice here would be to do a fresh install if possible (99% of cases). And if it’s really not possible, or you think it will take too long, do a full backup of your existing system, and try the upgrade on a separate device, just to see how it goes.

My experience

I did the test on two different setups, so you don’t have to. Here are my results.

With a desktop environment

In my experience, upgrading a desktop version of Raspberry Pi OS from Bullseye to Bookworm is not a good idea. Even if it looks good at first glance, there are many underlying bugs in the background.

After the first reboot, it seemed “OK” in my tests. But as soon as I started using the interface, I noticed some weird issues.

It works, but many things need some extra work to run properly.
For example:

• The Raspberry Pi configuration tool won’t work (the system not using the usual configuration).
  
• VNC won’t work (change from Real VNC to WayVNC not completely done).
• You won’t have the new default packages and apps (like Firefox not installed).
• Etc.

Depending on how you use your system, and if your existing applications continue to work or not, it’s not necessarily that bad. But expect to have many issues after the upgrade anyway.

You’ll have to consider the time saved by not reinstalling your existing apps vs the time lost with problems like that and future incompatibilities. In my opinion, it’s not worth the try.

Problems with future updates are what really scare me, to be honest. Even if it doesn’t seem so bad currently, I’m sure it will only become worse with time and new application updates.

In short, don’t try to upgrade an existing Raspberry Pi OS Bullseye installation to Bookworm directly. Installing a fresh version of Bookworm Desktop on a new media storage is highly recommended.

For a Lite installation

I also tested a Lite installation, where many changes coming with Bookworm are less significant: no display so the Wayland switch is not an issue, no audio in general, Wi-Fi not necessarily used, etc.

In the case of a server running Raspberry Pi OS Bullseye, I think it is way more possible to do the upgrade to Bookworm directly. You still need to take precautions (backups), but it’s doable.

It worked well in my tests. But to be honest, it was a fresh installation, without a ton of servers and apps running, so I can’t promise it will work smoothly for you.

Anyway, I think it’s smarter to try it for a server. As it’s always a headache to reinstall many servers from scratch, you can try to duplicate your SD card and upgrade it to see how it goes. If it’s not that bad, it might save you a lot of time.

Disclaimer: While you can follow the steps listed in the next section to upgrade Raspberry Pi OS to the latest version, you do so at your own risk. Chances are that some packages will no longer work. You may also lose configurations or personal data in the process, so make sure you have a full backup of your system first.

How to upgrade Raspberry Pi OS to Bookworm

As mentioned in the introduction, we use APT to update all the packages on the system (either directly or with a graphical tool intermediate). APT checks for new updates available on the repositories and suggests installation.

The easiest way to upgrade your system to a new version is to change the repositories used by APT.

So, start by opening a terminal.
You can do this via a GUI (Graphical User Interface), on Raspberry Pi OS Lite or even via an SSH connection, it doesn’t matter.

Start by updating your system with the current repositories, you want the latest packages available for the current version before upgrading everything to the latest one:
sudo apt update
sudo apt upgrade -y

Reboot the Raspberry Pi if there are many updates:
sudo reboot

Then, we’ll change the repositories used to upgrade to the latest Raspberry Pi OS (beta) version:

• Open the sources.list file with:
  sudo nano /etc/apt/sources.list
  If you are new to this editor, you can find my complete Nano guide with the commands and shortcuts here.
• You’ll see one or more lines like this:
  deb http://deb.debian.org/debian bullseye main contrib non-free
• Edit these lines and replace the current Debian code name with the one you want to install, for example:
  deb http://deb.debian.org/debian bookworm main contrib non-free
  If there are several lines, change all of them the same way (bookworm-security, bookworm-updates, etc.).
  
  It’s a good idea to update it step-by-step, one version at a time.
• Save and exit this file (CTRL+O, CTRL+X).

Note: Depending on your system versions and additional packages, you may have other configuration files under /etc/apt/sources.list.d. Edit them following the same steps.

The next step is to make a complete upgrade of your system:

• Update the package lists:
  sudo apt update
  
  As you can see, all the URLs now include “bookworm” instead of “bullseye”.
• Then upgrade everything with:
  sudo apt upgrade
• Press “Y” to confirm the installation.
  It will start downloading all the packages now. It might take a while, especially if you have a slow connection.
• Press “q” to exit the list of changes when it shows up.
• Depending on the packages you have, you might have to answer a few questions during the installation (overwrite configuration, restart services, etc.).
  
  So, you can’t even leave your screen for too long, it won’t do everything automatically :-).
• After that, I recommend running this other command to install the latest version of everything:
  sudo apt dist-upgrade
It’s not mandatory, but it’s generally recommended for a major upgrade like that, to make sure all dependencies are up-to-date and linked correctly to the latest version.
  It’s the same process, confirm the downloads with “Y”, press “q” to close the changes list, and wait a few more minutes to complete the installation.

It will take a while to download and install all the new packages (over 1000 in my case).
Once done, it’s a good idea to reboot your system to apply all changes directly:
sudo reboot

That’s it, I’m now up-to-date with Bookworm running on my Raspberry Pi 4:

Cleaning up

After the upgrade, you can generally save some disk space by running these commands:
sudo apt autoremove
sudo apt autoclean

This will uninstall the dependencies that are no longer required, and clean the packages cache.

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.