HOWTO: Upgrade Raspberry Pi OS from Bullseye to Bookworm

gistfile1.txt

### WARNING: READ CAREFULLY BEFORE ATTEMPTING ###
#
# Officially, this is not recommended. YMMV
# https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/
#
# This mostly works if you are on 64bit. You are on your own if you are on 32bit or mixed 64/32bit
#
# Credit to anfractuosity and fgimenezm for figuring out additional details for kernels
#

# Make sure everything is up-to-date
sudo apt-get update && sudo apt-get dist-upgrade

# Point to bookworm repos instead
sudo sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list
sudo sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list.d/raspi.list

# Contents of /etc/apt/sources.list
deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
# Uncomment deb-src lines below then 'apt-get update' to enable 'apt-get source'
#deb-src http://deb.debian.org/debian bookworm main contrib non-free
#deb-src http://security.debian.org/debian-security bookworm-security main contrib non-free
#deb-src http://deb.debian.org/debian bookworm-updates main contrib non-free

# Contents of /etc/apt/sources.list.d/raspi.list
deb http://archive.raspberrypi.org/debian/ bookworm main
# Uncomment line below then 'apt-get update' to enable 'apt-get source'
#deb-src http://archive.raspberrypi.org/debian/ bookworm main

# Do actual update
sudo apt update && sudo apt -y full-upgrade && sudo apt -y clean && sudo apt -y autoremove

# Reboot
sudo reboot

# Remove old config files after doing sanity checks
sudo apt purge ?config-files

### Switch to the new kernels ###
#
## WARNING: Since this has bitten several folks. The following can completely brick your system requiring a reinstall
##          DO NOT do this if you are unsure
#
# Prep
sudo dpkg --purge --force-depends raspberrypi-kernel raspberrypi-bootloader
sudo umount /boot
sudo fsck -y /boot
sudo mkdir /boot/firmware
sudo sed -i.bak -e "s#boot#boot/firmware#" /etc/fstab
sudo systemctl daemon-reload
sudo mount /boot/firmware
sudo apt install raspi-firmware

# Actually install the kernels. Make sure you pick the right version for your Pi
# sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8      # 64bit
# sudo apt install linux-image-rpi-v7l linux-headers-rpi-v7l    # 32bit
# sudo apt install linux-image-rpi-v6 linux-headers-rpi-v6      

# Append auto_initramfs=1 to the bottom of file where it says [all]
sudo sed -i.bak '$ a\auto_initramfs=1' /boot/firmware/config.txt 

# Reboot
sudo reboot

# Verify using "uname -a" (correct as of 10/2023)
# Old kernel
# Linux raspberrypi 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64 GNU/Linux
# New kernel
# Linux raspberrypi 6.1.0-rpi4-rpi-v8 #1 SMP PREEMPT Debian 1:6.1.54-1+rpt2 (2023-10-05) aarch64 GNU/Linux

# If you are not converted to using NetworkManager, you might lose networking upon reboot. 
# Check the ARP table to see what the new DHCP assigned IP address is. You may have to manually set the IP address again
# Thanks to solsticedhiver for identifying this
#
# Install NetworkManager if not already installed
sudo apt-get install --no-install-recommends network-manager
#
# Switch to NetworkManager from dhcpcd
sudo systemctl enable --now NetworkManager
sudo systemctl disable --now dhcpcd
#
# Set up static IP. Adjust as necessary 
sudo nmcli -p connection show 
sudo nmcli -p connection show "Wired connection 1"
sudo nmcli con mod "Wired connection 1" ipv4.method manual ipv4.addresses 192.168.1.5/24 ipv4.gateway 192.168.1.1

# Reboot
sudo reboot

#
# Bonus steps
#
# Install btop
sudo apt-get install btop
#
# Update /etc/ssh/sshd_config for up to date, secure by default config. Use ssh-audit to verify
KexAlgorithms sntrup761x25519-sha512@openssh.com,curve25519-sha256,curve25519-sha256@libssh.org
HostKeyAlgorithms ssh-ed25519-cert-v01@openssh.com,ssh-ed25519
# Ciphers chacha20-poly1305@openssh.com # Disabled due to CVE-2023-48795 for now
Ciphers aes128-gcm@openssh.com,aes256-gcm@openssh.com 
MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com

For the few users getting the error:

pi@raspberrypi:/etc/apt $ sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package linux-image-rpi-v8
E: Unable to locate package linux-headers-rpi-v8

It is likely you are upgrading from 32-bit to 64-bit or previously upgraded and saw your kernel with 64-bit, but didn't know your userland binaries were still using 32-bit.

You can verify by:

sudo dpkg --print-architecture

Which will likely show: armhf.

Then do:

sudo apt list linux-image-rpi*

You'll likely see all *armhf (32-bit) lines.

Since the package system is using 32-bit, it won't pull the needed 64-bit packages, including the kernel you want.

Check to see if you have another architecture enabled using:

sudo dpkg --print-foreign-architecture

It's likely blank.

If you want to add that 64-bit kernel:

sudo dpkg --add-architecture arm64

Then see the 64-bit package lists available for the kernel:

sudo apt list linux-image-rpi*

Now you should see the ...-V8 along with other *arm64 versions.

You can upgrade the kernel now, BUT you'll still be stuck with 32-bit userland binaries. Cross-grading from 32-bit to 64-bit can be done but it is tedious and requires around 6 to 8 hours for someone who has the skills. IMHO, it's not worth the time. You'll save a lot of time backing up your /home, /etc, /var, and other important directories or files along with the packages you installed. Install a fresh Bookworm 64-bit image, copy the backup files and directories over, and install those needed packages.

Updates:
2023-11-23 -- Seems the copy and paste with -- had some issues so I retyped the -- above to save you some errors.

For the few users getting the error:

pi@raspberrypi:/etc/apt $ sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package linux-image-rpi-v8
E: Unable to locate package linux-headers-rpi-v8

It is likely you are upgrading from 32-bit to 64-bit or previously upgraded and saw your kernel with 64-bit, but didn't know your userland binaries were still using 32-bit.

You can verify by:

sudo dpkg ‐-print-architecture

Which will likely show: armhf.

Then do:

sudo apt list linux-image-rpi*

You'll likely see all *armhf (32-bit) lines.

Since the package system is using 32-bit, it won't pull the needed 64-bit packages, including the kernel you want.

Check to see if you have another architecture enabled using:

sudo dpkg ‐-print-foreign-architecture

It's likely blank.

If you want to add that 64-bit kernel:

sudo dpkg ‐-add-architecture arm64

Then see the 64-bit package lists available for the kernel:

sudo apt list linux-image-rpi*

Now you should see the ...-V8 along with other *arm64 versions.

You can upgrade the kernel now, BUT you'll still be stuck with 32-bit userland binaries. [Cross-grading]

I am running Raspbian Homebridge version of Raspbian. I followed the instructions here and got the message about 'unable to locate package' for the v8 (arm64) kernel

I installed the v7 (32bit) kernel and its working, but on a clone of this Rpi that has not been upgraded it was a 64bit kernel and 32bit userland. I'd like to get this system back to that, but when I run

sudo dpkg ‐-add-architecture arm64

it says

dpkg: error: need an action option

any ideas?

but when I run

sudo dpkg ‐-add-architecture arm64

it says

dpkg: error: need an action option

It seem the comment from @thomastthai has an incorrect character in place of the first "-" in the various sudo dpkg --something commands. It looks almost identical (depending on the font), but it will cause this error if you've copy/pasted the command.
You just need to delete the two dash characters and type them yourself.

but when I run
sudo dpkg ‐-add-architecture arm64
it says
dpkg: error: need an action option

It seem the comment from @thomastthai has an incorrect character in place of the first "-" in the various sudo dpkg --something commands. It looks almost identical (depending on the font), but it will cause this error if you've copy/pasted the command. You just need to delete the two dash characters and type them yourself.

Thank you, that did allow me to add the arm64 architecture, but when I try to

sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8

it still gives me an error that it is not found
When I try to do a

sudo apt update

I get new warnings about a deprecated key and notes like this

N: Skipping acquire of configured file 'main/binary-arm64/Packages' as repository 'http://raspbian.raspberrypi.org/raspbian bookworm InRelease' doesn't support architecture 'arm64'

@fgimenezm

linux-image-rpi-v8 Is 64bit Read the comment right before yours

I know. I tired also to run instead:

sudo apt install linux-image-rpi-v7l linux-headers-rpi-v7l

But had the same result.

I ended up with a fresh install.

Perhaps there is already a solution on the comments above, but I reinstalled it a few weeks ago.

Awesome guide, thank you!
My 5c - upgraded my two Pis, the prickliest part was the NetworkManager in both cases.

In one case the machine was unable to connect even via cable after switching off dhcpcd, managed to revert via booting from SD card, mounting my SSD and doing

sudo chroot /mountdir sh
sudo systemctl enable dhcpcd

Afterwards I found that the correct way to switch to NetworkManager is to use raspi-config, which worked like a charm.

For Pi 5 there is a 2712 kernel, but it works with v8 as well.

Since bookworm, the files /boot/cmdline.txt and /boot/config.txt have been moved to the /boot/firmware/ folder.

In a fresh install, there are files have been replaced by links, here's how to align this change:

cd /boot
sudo ln -s firmware/cmdline.txt cmdline.txt
sudo ln -s firmware/config.txt config.txt

Note that your Raspberry will be functional without these links, but this may be the source of errors with some tools or tutorials.

@cClaude It's already accounted for here: https://gist.github.com/jauderho/6b7d42030e264a135450ecc0ba521bd8#file-gistfile1-txt-L45

Hey, thanks, I've used your guide and all OK and running an updated OS.

This kinda works on a 32bit original Raspberry Pi B

I am using the same, but upon apt update I get these warnings:

sudo apt update
Hit:1 http://apt.mopidy.com bookworm InRelease
Hit:2 http://archive.raspberrypi.org/debian bookworm InRelease                                               
Hit:3 http://raspbian.raspberrypi.org/raspbian bookworm InRelease                                            
Hit:4 https://deb.nodesource.com/node_20.x nodistro InRelease             
Reading package lists... Done                       
Building dependency tree... Done
Reading state information... Done
All packages are up to date.
W: Skipping acquire of configured file 'non-free-firmware/binary-armhf/Packages' as repository 'http://raspbian.raspberrypi.org/raspbian bookworm InRelease' doesn't have the component 'non-free-firmware' (component misspelt in sources.list?)
W: Skipping acquire of configured file 'non-free-firmware/i18n/Translation-en_GB' as repository 'http://raspbian.raspberrypi.org/raspbian bookworm InRelease' doesn't have the component 'non-free-firmware' (component misspelt in sources.list?)
W: Skipping acquire of configured file 'non-free-firmware/i18n/Translation-en' as repository 'http://raspbian.raspberrypi.org/raspbian bookworm InRelease' doesn't have the component 'non-free-firmware' (component misspelt in sources.list?)

Is this for headless setups only or desktops as well? Does wayland work?

I installed the wrong kernel image (linux-image-rpi-v7l) on my rpi3 and now it won't boot (blinking green seven times).
Can i fix this by just copying kernel7.img to the sd card or will I need to boot up a running system and running rpi-update chrooted on the sd?

Edit: okay copying the correct kernel.img to the card actually made it boot again. What confused me in the first place is that uname -a shows "armv7l" but the rpi-v7l package is not the correct one"

Another edit: I had to use rpi-update to get the latest kernel

@leoguiders what is the correct kernel.img in your case? It looks like v7l is what is needed for 32bit pi 3.

@thomastthai

In your comment regarding finding architecture, there is a typo

Check to see if you have another architecture enabled using:
sudo dpkg --print-foreign-architecture

It should be
sudo dpkg --print-foreign-architectures

How to add missing public keys without using apt-key as it is deprecated

This method will automatically download all missing keys without needing to reference each public key separately.

• Create a bash script:
  sudo nano ~/Desktop/addkey.sh

• Script will contain the following code:
  #!/bin/sh -e
tmp="$(mktemp)"
sudo apt-get update 2>&1 | sed -En 's/.*NO_PUBKEY ([[:xdigit:]]+).*/\1/p' | sort -u > "${tmp}"
cat "${tmp}" | xargs sudo gpg --homedir ~/.gnupg --keyserver "hkps://keyserver.ubuntu.com:443" --recv-keys # saved to ~/.gnupg
cat "${tmp}" | xargs -L 1 sh -c 'sudo gpg --yes --output "/usr/share/keyrings/$1.gpg" --export "$1"' sh # to /usr/share/keyrings/*
rm "${tmp}"

• Make script executable:
  sudo chmod +x ~/Desktop/addkey.sh

• Run script (ignore error about unsafe ownership on homedir). If you get key not found, it means no keys are missing.
  ~/Desktop/addkey.sh

• Copy all exported keys to a location apt will check
  sudo cp /usr/share/keyrings/* /etc/apt/trusted.gpg.d

• Now you can run
  sudo apt update

How to configure Network Manger using the text user interface

• This allows you to add, edit, or delete connections very easily (including WiFi, Ethernet, VLAN, bridging connections, etc)
  sudo nmtui

• For example, adding a WiFi connection:

  • Give connection a name, can be same as your SSID
  • To get device name, use the following command, but it typically is something like wlan0, wlan1, etc:
    nmcli device
  • Leave mode as client
  • Choose security type if WiFi access point is secured. Most people will choose WPA & WPA2 Personal.
  • Enter the password
  • You can leave IPV4 as automatic or you can set static by changing to manual and hitting show to reveal the fields.

• After I enabled Network Manager and added my networks, I actually removed dhcpcd, so there is no competing services
  sudo apt purge dhcpcd

Two questions on this great guide and comments:

1. I wonder why the # Contents of /etc/apt/sources.list listed there are defaulting to Debian sources
   (e. g. deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware)
   instead of the Raspberry Pi sources
   (e. g. deb http://raspbian.raspberrypi.org/raspbian/ bookworm main contrib non-free rpi)
   What's the reason / advantage of doing this?

2. Section ### Switch to the new kernels ### (lines 39 + 56):
   Is this needed in general? For firmware updates there's the native rpi-update, isn't that much easier?
   Edit: None of those two ways was necessary for one of my upgraded Pi's: the 6.1.y linux tree kernel was already shipped with the updated apt packages (now running 6.1.21-v7+ #1642 SMP Mon Apr 3 17:20:52 BST 2023 armv7l GNU/Linux).

@bcutter I believe the debian repositories are for 64-bits. It is not needed to switch to the new kernels, but it is quite recommended.

@fmarzocca

• on 1: Well Raspbian offers 64 bit packages since early 2022.
• on 2: Upgrading the kernel yes, but to specify my question: is the (quite complicated) way needed over just using rpi-update?

Since bookworm, the files /boot/cmdline.txt and /boot/config.txt have been moved to the /boot/firmware/ folder.

In a fresh install, there are files have been replaced by links, here's how to align this change:

cd /boot
sudo ln -s firmware/cmdline.txt cmdline.txt
sudo ln -s firmware/config.txt config.txt

Note that your Raspberry will be functional without these links, but this may be the source of errors with some tools or tutorials.

Note that on a Pi 2 (armhf) with 6.1.21-v7+ #1642 SMP Mon Apr 3 17:20:52 BST 2023 armv7l GNU/Linux after upgrading from Bullseye to Bookworm there's no firmware folder at all. Probably that only applies to 64 bit? In the source .ISO file the firmware folder exists but is empty.

@bcutter this is only valid if you also upgrade to the new kernel

@bcutter this is only valid if you also upgrade to the new kernel

...which is what happens (happened for me) automatically as the new kernel is part of the updated apt sources.

It was not automatic for me. After a full upgrade with the new repositories, I continued using the Raspi with the old kernel for a week, before applying the procedure to upgrade to the new kernel.

kernel.img

I installed the wrong kernel image (linux-image-rpi-v7l) on my rpi3 and now it won't boot (blinking green seven times). Can i fix this by just copying kernel7.img to the sd card or will I need to boot up a running system and running rpi-update chrooted on the sd?

Edit: okay copying the correct kernel.img to the card actually made it boot again. What confused me in the first place is that uname -a shows "armv7l" but the rpi-v7l package is not the correct one"

Another edit: I had to use rpi-update to get the latest kernel

Same for me. I checked before with

• arch
• uname -m
• sudo dpkg --print-architecture

and it gave me armv7l which is why I choosed sudo apt install linux-image-rpi-v7l linux-headers-rpi-v7l # 32bit.

• After reboot ended up in 7x green LED which stands for "kernel.img not found". Swapped the kernel7l.img (created by the Pi) by kernel7.img (from image freshly downloaded from website), boot possible again ✅
• Thought about "maybe I should also swap initramfs7l by initramfs7?". Did so, after that the ACT LED was permanently green, no boot possible anymore ❌
• So back to the working setup: kernel7.img with the initramfs7l. ✅

So I strongly advice to rework that section (lines 50 to 53) as it really causes troubles.

---

I only went through the process for educational reasons on my test Pi. As mentioned, kernel got already updated to 6.1.21-v7+ #1642 SMP Mon Apr 3 17:20:52 BST 2023 armv7l GNU/Linux.
Now after running this additional kernel update section including the kernel trouble I landed at 6.1.0-rpi7-rpi-v7 #1 SMP Raspbian 1:6.1.63-1+rpt1 (2023-11-24) armv7l GNU/Linux - which is strange: the version is lower (6.1.0 instead of 6.1.21) but the date is newer (2023-11-24 instead of 2023-04-03).

• I didn't want to continue with that "felt mess" and simply used rpi-update.
• ...which did not work out as the boot partition was too small. And I really did not want to go through the way highlighted at https://gist.github.com/jauderho/6b7d42030e264a135450ecc0ba521bd8?permalink_comment_id=4760043#gistcomment-4760043 as that would've cost me additionally I guess almost 2 hours.
• **So I tried with sudo apt install raspberrypi-kernel raspberrypi-bootloader.
  Unfortunately it seems like the "mix" stays with uname -a giving 6.1.0-rpi7-rpi-v7 #1 SMP Raspbian 1:6.1.63-1+rpt1 (2023-11-24) armv7l GNU/Linux and now a very interesting /boot content with filled /boot (from apt raspberrypi-kernel) as well as /boot/firmware (from the manual hack way).

In the end I really should have stayed with the kernel shipped with the apt sources instead of walking that hacky path in lines 39 to 53 and purely wasting time for nothing.
I'll see how things go for my other Pi's.

I agree with @bcutter . Trying to upgrade the kernel only caused more issues and led to a non-bootable situation for me. Tried to recover by manually copying the kernel .img but didn't work.

In the end, I just did a fresh install of bookworm. That's what I would recommend until the kernel upgrade process is understood better for different situations.

By the way, my situation was 64-bit kernel with 32-bit userland.
I had the identical old kernel to the OP: Linux raspberrypi 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr 3 17:24:16 BST 2023 aarch64 GNU/Linux
I added the arm64 architecture using sudo dpkg --add-architecture arm64
Tried to run sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8 which kept failing because it couldn't install the necessary 64 bit dependencies.

Maybe it had something to do with the purge and/or lines 39-48 in the current guide. But like I said, I gave up and did a fresh install to convert to a full 64 bit environment rather than try to cross-grade from 32 bit to 64 bit. For anyone that does want to try it, here's a guide that may or may not work: https://wiki.debian.org/Migrate32To64Bit

Thanks for the guide it worked perfectly.

Great guide, succinct, and it works!

If you ignored the below warning and your system is not booting. Are you getting blank screen and the green LED on your Raspberry Pi is flashing 8 times while the red LED is on. It is ok, it can be fixed. Tested on Raspberry Pi 3B+.

## WARNING: Since this has bitten several folks. The following can completely brick your system requiring a reinstall
##          DO NOT do this if you are unsure

1. Using the Raspbian imager, install a fresh copy on a USB drive (Not your SDcard).
2. Backup the content of the boot of your SDcard.
3. Replace the content of the SDcard boot volume with the content of boot volume from the USB drive.
4. Restore the file cmdline.txt from the backup that you took. (This is important so you can restore the correct PARTUUID)
5. Put the SDcard back into your Raspberry Pi and check if the problem is resolved.

If your system starts fine but still can't get into your Desktop, hit Ctrl+Alt+F1 to get into your terminal (or use SSH). From there run sudo raspi-config.
Select "Advanced Options" --> "Wayland" --> "Wayfire". Go back to the main screen and hit "Finish" to save and reboot.

Worked great for me on a whole rack of 8 4Bs. I would recommend going here: https://www.ssh.com/ssh/sshd_config/ for the latest updates on Ciphers, Algos and MACs as these change quite frequently. The only thing I am disappointed with is that Bookworm still isn't running with GCC-13.2.0 in the stable repo like almost every other distro out there, but I know Debian is all about taking their time in the name of stability. The reason upgrading like this is probably not recommended is that for each step, it may not be cut and dried and you may have to make decisions specific to your system and configuration. For example, whether to keep your custom config files for certain services or to go with the new clean one from updated package maintainers. You definitely need to know what you are doing and you should experiment with a system you don't care too much about before you roll this procedure everywhere IMO. That said, was smooth sailing over here with a couple of additional decisions to make along the way. Thank you to jauderho for the gist - saved me lots of time.

@jnorrid,
Hello, sir.

Could you check and yield your kernel version after update? Is it 6.6.*?

Thanks.

Yes @stdenits - no problem. On my system, uname -a yields:

6.6.20+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.6.20-1+rpt1 (2024-03-07) aarch64

This saved me a bunch of time and worked beautifully on a Pi4B running bullseye on 64bit userland - including the change to the firmware folder. Thank you!