I’ve been getting annoyed with Raspberry Pi OS (Raspbian) for years now. It’s a fork of Debian, but manages to omit some of the most useful things. So I’ve decided to migrate all of my Pis to run pure Debian. These are my reasons:
- Raspberry Pi OS has, for years now, specified that there is no upgrade path. That is, to get to a newer major release, it’s a reinstall. While I have sometimes worked around this, for a device that is frequently installed in hard-to-reach locations, this is even more important than usual. It’s common for me to upgrade machines for a decade or more across Debian releases and there’s no reason that it should be so much more difficult with Raspbian.
- As I noted in Consider Security First, the security situation for Raspberry Pi OS isn’t as good as it is with Debian.
- Raspbian lags behind Debian – often times by 6 months or more for major releases, and days or weeks for bug fixes and security patches.
- Raspbian has no direct backports support, though Raspberry Pi 3 and above can use Debian’s backports (per my instructions as Installing Debian Backports on Raspberry Pi)
- Raspbian uses a custom kernel without initramfs support
It turns out it is actually possible to do an in-place migration from Raspberry Pi OS bullseye to Debian bookworm. Here I will describe how. Even if you don’t have a Raspberry Pi, this might still be instructive on how Raspbian and Debian packages work.
Before continuing, back up your system. This process isn’t for the neophyte and it is entirely possible to mess up your boot device to the point that you have to do a fresh install to get your Pi to boot. This isn’t a supported process at all.
Debian has three ARM-based architectures:
- armel, for the lowest-end 32-bit ARM devices without hardware floating point support
- armhf, for the higher-end 32-bit ARM devices with hardware float (hence “hf”)
- arm64, for 64-bit ARM devices (which all have hardware float)
Although the Raspberry Pi 0 and 1 do support hardware float, they lack support for other CPU features that Debian’s armhf architecture assumes. Therefore, the Raspberry Pi 0 and 1 could only run Debian’s armel architecture.
Raspberry Pi 3 and above are capable of running 64-bit, and can run both armhf and arm64.
Prior to the release of the Raspberry Pi 5 / Raspbian bookworm, Raspbian only shipped the armhf architecture. Well, it was an architecture they called armhf, but it was different from Debian’s armhf in that everything was recompiled to work with the more limited set of features on the earlier Raspberry Pi boards. It was really somewhere between Debian’s armel and armhf archs. You could run Debian armel on those, but it would run more slowly, due to doing floating point calculations without hardware support. Debian’s raspi FAQ goes into this a bit.
What I am going to describe here is going from Raspbian armhf to Debian armhf with a 64-bit kernel. Therefore, it will only work with Raspberry Pi 3 and above. It may theoretically be possible to take a Raspberry Pi 2 to Debian armhf with a 32-bit kernel, but I haven’t tried this and it may be more difficult. I have seen conflicting information on whether armhf really works on a Pi 2. (If you do try it on a Pi 2, ignore everything about arm64 and 64-bit kernels below, and just go with the
linux-image-armmp-lpae kernel per the ARMMP page)
There is another wrinkle: Debian doesn’t support running 32-bit ARM kernels on 64-bit ARM CPUs, though it does support running a 32-bit userland on them. So we will wind up with a system with kernel packages from arm64 and everything else from armhf. This is a perfectly valid configuration as the arm64 – like x86_64 – is multiarch (that is, the CPU can natively execute both the 32-bit and 64-bit instructions).
(It is theoretically possible to crossgrade a system from 32-bit to 64-bit userland, but that felt like a rather heavy lift for dubious benefit on a Pi; nevertheless, if you want to make this process even more complicated, refer to the CrossGrading page.)
Prerequisites and Limitations
In addition to the need for a Raspberry Pi 3 or above in order for this to work, there are a few other things to mention.
If you are using the GPIO features of the Pi, I don’t know if those work with Debian.
I think Raspberry Pi OS modified the desktop environment more than other components. All of my Pis are headless, so I don’t know if this process will work if you use a desktop environment.
I am assuming you are booting from a MicroSD card as is typical in the Raspberry Pi world. The Pi’s firmware looks for a FAT partition (MBR type 0x0c) and looks within it for boot information. Depending on how long ago you first installed an OS on your Pi, your /boot may be too small for Debian. Use
df -h /boot to see how big it is. I recommend 200MB at minimum. If your /boot is smaller than that, stop now (or use some other system to shrink your root filesystem and rearrange your partitions; I’ve done this, but it’s outside the scope of this article.)
You need to have stable power. Once you begin this process, your pi will mostly be left in a non-bootable state until you finish. (You… did make a backup, right?)
The basic idea here is that since bookworm has almost entirely newer packages then bullseye, we can “just” switch over to it and let the Debian packages replace the Raspbian ones as they are upgraded. Well, it’s not quite that easy, but that’s the main idea.
First, make a backup. Even an image of your MicroSD card might be nice. OK, I think I’ve said that enough now.
It would be a good idea to have a HDMI cable (with the appropriate size of connector for your particular Pi board) and a HDMI display handy so you can troubleshoot any bootup issues with a console.
The Raspberry Pi OS by default sets up a user named
pi that can use
sudo to gain root without a password. I think this is an insecure practice, but assuming you haven’t changed it, you will need to ensure it still works once you move to Debian. Raspberry Pi OS had a patch in their sudo package to enable it, and that will be removed when Debian’s sudo package is installed. So, put this in
pi ALL=(ALL) NOPASSWD: ALL
Also, there may be no password set for the root account. It would be a good idea to set one; it makes it easier to log in at the console. Use the
passwd command as root to do so.
Debian doesn’t correctly identify the Bluetooth hardware address. You can save it off to a file by running
hcitool dev > /root/bluetooth-from-raspbian.txt. I don’t use Bluetooth, but this should let you develop a script to bring it up properly.
Preparation: Debian archive keyring
You will next need to install Debian’s archive keyring so that apt can authenticate packages from Debian. Go to the bookworm download page for debian-archive-keyring and copy the URL for one of the files, then download it on the pi. For instance:
sha256sum to verify the checksum of the downloaded file, comparing it to the package page on the Debian site.
Now, you’ll install it with:
dpkg -i debian-archive-keyring_2023.3+deb12u1_all.deb
Package first steps
From here on, we are making modifications to the system that can leave it in a non-bootable state.
/etc/apt/sources.list and all the files in
/etc/apt/sources.list.d. Most likely you will want to delete or comment out all lines in all files there. Replace them with something like:
deb http://deb.debian.org/debian/ bookworm main non-free-firmware contrib non-free
deb http://security.debian.org/debian-security bookworm-security main non-free-firmware contrib non-free
deb https://deb.debian.org/debian bookworm-backports main non-free-firmware contrib non-free
(you might leave off contrib and non-free depending on your needs)
Now, we’re going to tell it that we’ll support arm64 packages:
dpkg --add-architecture arm64
And finally, download the bookworm package lists:
If there are any errors from that command, fix them and don’t proceed until you have a clean run of
Moving /boot to /boot/firmware
The boot FAT partition I mentioned above is mounted at
/boot by Raspberry Pi OS, but Debian’s scripts assume it will be at
/boot/firmware. We need to fix this. First:
Now, edit fstab and change the reference to
/boot to be to
mount -v /boot/firmware
mv -vi * ..
This mounts the filesystem at the new location, and moves all its contents back to where apt believes it should be. Debian’s packages will populate
Installing the first packages
Now we start by installing the first of the needed packages. Eventually we will wind up with roughly the same set Debian uses.
apt-get install linux-image-arm64
apt-get install firmware-brcm80211=20230210-5
apt-get install raspi-firmware
If you get errors relating to firmware-brcm80211 from any commands, run that
install firmware-brcm80211 command and then proceed. There are a few packages that Raspbian marked as newer than the version in bookworm (whether or not they really are), and that’s one of them.
Configuring the bootloader
We need to configure a few things in
/etc/default/raspi-firmware before proceeding. Edit that file.
First, uncomment (or add) a line like this:
/boot/cmdline.txt you can find your old Raspbian boot command line. It will say something like:
Save off the bit starting with
PARTUUID. Back in
/etc/default/raspi-firmware, set a line like this:
(substituting your real value for abcdef00).
This is necessary because the microSD card device name often changes from
/dev/mmcblk1 when switching to Debian’s kernel.
raspi-firmware will encode the current device name in
/boot/firmware/cmdline.txt by default, which will be wrong once you boot into Debian’s kernel. The
PARTUUID approach lets it work regardless of the device name.
Purging the Raspbian kernel
dpkg --purge raspberrypi-kernel
Upgrading the system
At this point, we are going to run the procedure beginning at section 4.4.3 of the Debian release notes. Generally, you will do:
apt-get -u upgrade
Fix any errors at each step before proceeding to the next. Now, to remove some cruft, run:
apt-get --purge autoremove
Inspect the list to make sure nothing important isn’t going to be removed.
Removing Raspbian cruft
You can list some of the cruft with:
apt list '~o'
And remove it with:
apt purge '~o'
I also don’t run Bluetooth, and it seemed to sometimes hang on boot becuase I didn’t bother to fix it, so I did:
apt-get --purge remove bluez
Installing some packages
This makes sure some basic Debian infrastructure is available:
apt-get install wpasupplicant parted dosfstools wireless-tools iw alsa-tools
apt-get --purge autoremove
apt-get install firmware-linux
Resolving firmware package version issues
If it gives an error about the installed version of a package, you may need to force it to the bookworm version. For me, this often happened with
Here’s how to resolve it, with
firmware-realtek as an example:
https://packages.debian.org/PACKAGENAME– for instance, https://packages.debian.org/firmware-realtek. Note the version number in bookworm – in this case, 20230210-5.
Now, you will force the installation of that package at that version:
apt-get install firmware-realtek=20230210-5
Repeat with every conflicting package until done.
apt-get install firmware-linuxand make sure it runs cleanly.
Also, in the end you should be able to:
apt-get install firmware-atheros firmware-libertas firmware-realtek firmware-linux
Dealing with other Raspbian packages
The Debian release notes discuss removing non-Debian packages. There will still be a few of those. Run:
apt list '?narrow(?installed, ?not(?origin(Debian)))'
Deal with them; mostly you will need to force the installation of a bookworm version using the procedure in the section Resolving firmware package version issues above (even if it’s not for a firmware package). For non-firmware packages, you might possibly want to add
--mark-auto to your
apt-get install command line to allow the package to be autoremoved later if the things depending on it go away.
If you aren’t going to use Bluetooth, I recommend
apt-get --purge remove bluez as well. Sometimes it can hang at boot if you don’t fix it up as described above.
Set up networking
We’ll be switching to the Debian method of networking, so we’ll create some files in
eth0 should look like this:
iface eth0 inet dhcp
iface eth0 inet6 auto
wlan0 should look like this:
iface wlan0 inet dhcp
Raspbian is inconsistent about using eth0/wlan0 or renamed interface. Run
ip addr. If you see a long-named interface such as enx<something> or wlp<something>, copy the
eth0 file to the one named after the enx interface, or the
wlan0 file to the one named after the wlp interface, and edit the internal references to eth0/wlan0 in this new file to name the long interface name.
If using wifi, verify that your SSIDs and passwords are in
/etc/wpa_supplicant/wpa_supplicant.conf. It should have lines like:
(This is where Raspberry Pi OS put them).
Deal with DHCP
Raspberry Pi OS used dhcpcd, whereas bookworm normally uses
isc-dhcp-client. Verify the system is in the correct state:
apt-get install isc-dhcp-client
apt-get --purge remove dhcpcd dhcpcd-base dhcpcd5 dhcpcd-dbus
Set up LEDs
To set up the LEDs to trigger on MicroSD activity as they did with Raspbian, follow the Debian instructions. Run
apt-get install sysfsutils. Then put this in a file at
class/leds/ACT/brightness = 1
class/leds/ACT/trigger = mmc1
Prepare for boot
To make sure all the
/boot/firmware files are updated, run
update-initramfs -u. Verify that
/boot/firmware/cmdline.txt references the
PARTUUID as appropriate. Verify that
/boot/firmware/config.txt contains the lines
upstream_kernel=1. If not, go back to the section on modifying
/etc/default/raspi-firmware and fix it up.
The moment arrives
Cross your fingers and try rebooting into your Debian system:
For some reason, I found that the first boot into Debian seems to hang for 30-60 seconds during bootstrap. I’m not sure why; don’t panic if that happens. It may be necessary to power cycle the Pi for this boot.
If things don’t work out, hook up the Pi to a HDMI display and see what’s up. If I anticipated a particular problem, I would have documented it here (a lot of the things I documented here are because I ran into them!) So I can’t give specific advice other than to watch boot messages on the console. If you don’t even get kernel messages going, then there is some problem with your partition table or
/boot/firmware FAT partition. Otherwise, you’ve at least got the kernel going and can troubleshoot like usual from there.