It’s an odd-numbered year, so there is a new major Debian release, and we are now releasing the corresponding version of Raspberry Pi OS.
This year’s Debian release is called Bookworm. (As you probably know, Debian releases are named after characters in Disney/Pixar’s Toy Story franchise, but there have now been so many releases that all the characters you might have heard of have already been used. Bookworm was a minor character in Toy Story 3 — and no, I didn’t remember him either…)
So what is new in Bookworm? Well, not a great deal… and yet pretty much everything. Allow me to explain.
Debian Bookworm itself is mostly made up of incremental updates of the software that was in the previous Debian Bullseye release. There are a few small changes — have a look here for the list — but they mostly won’t affect Raspberry Pi users. So Bookworm itself really hasn’t resulted in many changes.
However, for the last year or so we have been working on some major architectural changes to the Raspberry Pi Desktop, and these are launched for the first time in the Bookworm release. And this is where you might notice some differences.
Wayland
The most important of these is the move to using Wayland rather than X11 as the display system.
For the last 35 years or so, most Unix desktop environments, including the Raspberry Pi Desktop, have been based on the X11 window system. But, as is hardly surprising for a piece of software several decades old, X11 has various limitations when used on modern computers. To address these, most Linux distributions are moving to use Wayland; those which have not already done so are planning to do so in the future.
The primary advantage of Wayland is performance. Under X11, there are two separate applications involved in drawing a window. The display server is used to create windows on the screen and to give applications a place to draw their content; the window manager is used to position windows relative to each other and to decorate windows with title bars and frames. Under a Wayland system, these two functions are combined in a single application, called the compositor, so an application only needs to talk to one thing rather than two in order to get its windows drawn.
This also gives a security advantage. Because under X11 all applications were communicating with the display server, and this communication was two-way, all applications could exchange information with each other. Under Wayland, applications are all isolated from each other at the compositor level, so no application can see what another application is doing.
Wayland itself is just a protocol. In order to use it, you need a compositor which supports Wayland. In the previous release of Raspberry Pi OS, we were using the Mutter window manager, which could function as a Wayland compositor. But this turned out to have been a poor choice; it was relatively slow and cumbersome, and was a little out of date, which is why we only offered Wayland support on an experimental basis under Bullseye.
For Bookworm, we are using a compositor called Wayfire. This uses a standard Wayland library called wlroots, which is used by several modern Wayland compositors. And because Wayfire works a lot better as a Wayland compositor on Raspberry Pi than Mutter did, Wayland is now the default mode of operation for the desktop. (With one caveat — for now, Wayland is only the default on Raspberry Pi 4 and 5. The performance of Wayfire on earlier platforms is still being optimised, so for now they will continue to run the old X11 display server and the Openbox window manager, but at some point these platforms will also be switched to Wayfire.)
If you boot Raspberry Pi OS on a Pi 4 or 5, you will now get a Wayfire desktop. It should look pretty much identical to the desktop you are used to from Bullseye, but appearances are deceptive — it has taken a lot of work to get to the point where the two desktop environments look the same!
There is still a taskbar at the top of the screen that allows you to launch applications and see the status of various systems, but this is a totally new application. Under Bullseye, this was an application called lxpanel, but this has now been replaced with wf-panel-pi (short for “wayfire panel for Raspberry Pi”).
This was based on wf-shell, the example panel application from the authors of Wayfire, but we have extensively modified it to look and work like lxpanel. The largest part of this work was to port all the existing lxpanel plugins — the icons which control volume, network, Bluetooth, etc — so that they now all work with wf-panel-pi.
The desktop background itself is still drawn by the old pcmanfm file manager which was used under Bullseye, but this has been modified so that it uses Wayland as its display protocol rather than X11, so is now a native Wayland application.
How individual applications work in a Wayland environment depends on how they are written. The standard graphics toolkits, like GTK and Qt, are now Wayland-compliant — they can detect when an application using them is running in a Wayland environment, and they then route all graphics calls over the Wayland protocol, running as native Wayland applications. Most applications preinstalled as part of the Raspberry Pi Desktop use one of these toolkits, and so now run as Wayland applications.
A few applications use a toolkit which is not Wayland-compliant, or bypass a toolkit completely by making direct calls to X11. While it looks as if these applications wouldn’t work on Wayland, there is a fix for that. Our Wayland implementation includes a piece of software called XWayland — this is an X11 display server which sits on top of Wayland. It handles all the non-graphical parts of X itself, and passes any graphical parts to the underlying Wayland implementation. XWayland is designed to launch automatically as soon as an application requests anything from X, so this should all work seamlessly.
So that’s Wayland. Basically, everything you see on the desktop is now being drawn completely differently from the way it was drawn under Bullseye — but if I have done my job right, you shouldn’t notice any significant differences! One thing you might notice is that Wayland allows us to add some nice eye candy; windows now have subtle shadows, and they open and close with animations rather than just appearing and disappearing.
We’ve also added a couple of new plugins. The “Power” plugin is enabled by default, and monitors for power supply problems like low power supply voltage or excess USB current. If either occur, a notification will be displayed to let you know what has happened, and an icon is then shown on the taskbar — clicking this takes you to a web page with more information on the problem and possible fixes.
The other new plugin is “GPU”, which shows a graph of the load on the Raspberry Pi’s GPU, similar to that which the existing CPU plugin showed for the CPU. This is not enabled by default, but can be added by right-clicking the taskbar and choosing “Add/Remove Plugins”.
As mentioned above, work on Wayland/Wayfire is ongoing — we are still optimising for the hardware of earlier models of Raspberry Pi, and hope to be able to roll out the Wayland desktop experience for all models of Raspberry Pi in due course.
PipeWire
So, we’ve changed what is used to draw all the graphics. To go along with that, we’ve also changed what is used to control the sound.
Originally, the desktop used the Linux ALSA sound interface to communicate with audio hardware. This worked, but was pretty primitive and had numerous limitations. A few years ago, we switched to using the PulseAudio interface, which sits on top of the low-level ALSA layer. This added a lot more flexibility: it made it easier to manage things like Bluetooth audio devices, allowed audio from multiple applications to be mixed together, and allowed audio to easily be switched between outputs while playing.
For this release, PulseAudio has been replaced with the newer PipeWire audio system. This builds on the features offered by PulseAudio, most importantly in providing better support for audio accompanying video. It reduces latency, which is important in many applications. It manages Bluetooth audio devices better, remembering which ones were in use at power-down, and automatically reconnecting them at boot. Finally, it is designed to operate better in the more secure Wayland environment, where applications are isolated from each other.
From a user point of view, PipeWire can be controlled with any application which controls PulseAudio, so the volume and microphone controls on the taskbar work exactly as they did under PulseAudio, but under Bookworm, they are talking to PipeWire rather than PulseAudio.
Networking
Graphics and sound are both new then — what else?
During Bullseye, we rolled out the use of the NetworkManager network controller as an option which could be selected in raspi-config. This is now the standard control mechanism for networking in most Linux distributions, and is now the default network controller for Bookworm, replacing the previous system, dhcpcd. NetworkManager does everything dhcpcd did, but adds a bunch of extra functionality, including the ability to connect to hidden wireless networks, to connect to virtual private networks (VPNs), and to use a Raspberry Pi as a wireless hotspot. It also includes a lot more customisation options for those who wish to fiddle with the nitty-gritty of their network connection.
The networking plugin on the taskbar looks almost identical to that which controlled dhcpcd in Bullseye, but now has an “Advanced Options” item at the bottom — this allows you to access the new functionality offered by NetworkManager.
Firefox
One other significant change is that we are now offering a second browser option, with the launch of a Raspberry Pi-optimised version of Mozilla Firefox.
This is the first time we’ve officially supported Firefox — previously, the only version available was an old version from Debian, whereas we’ve now done a lot of work to ensure the best possible experience when running the latest version of Firefox on Raspberry Pi. We’ve worked closely with Mozilla and the Firefox community, and we’re contributing our work upstream to benefit Firefox users on all platforms.
One key feature has been enabling V4L2 codec support so that Firefox can utilise the hardware h.264 decoder on Raspberry Pi. On older models of Raspberry Pi, this significantly improves performance and reduces CPU load when playing back HD video. We’ve enabled support for Widevine DRM, which is used by a number of video streaming services, and have contributed graphical optimisations that improve performance on a range of websites on low-power devices. For video calling we’ve made sure that Firefox on Raspberry Pi OS works out of the box with CSI cameras (using libcamera) and desktop sharing on Wayland.
Documentation
As you’d expect from such sweeping changes, there were huge knock-on effects to our documentation, and the documentation team has been working away behind the scenes making sure that it reflects the new state of the world. This is true especially around things l haven’t even had space to mention here, like the changes to how Python modules are installed.
It’s been a huge effort, with a lot of changes across the entire documentation stack, so if you do stumble across a place where the documentation hasn’t been updated for Bookworm, please raise an issue on the documentation repo!
What’s missing?
With any change as significant as this, it can be difficult to make sure that everything from the old version still works under the new one, and while we have tried very hard to keep such things to a minimum, there are a few features which we haven’t been able to get into this release.
- Compensation for displays which use overscan is tricky under Wayland, and we haven’t quite got it working yet, so this has been removed for now. The vast majority of displays nowadays don’t need it, but we will be putting it back when we have worked out how best to do it!
- The system tray — the area on the taskbar where applications can put their own icons — has to use a completely new mechanism to work with Wayland’s security model. This means that some applications may need to be updated in order for their icons to appear there.
- Similarly, the Wayland security model prevents traditional remote desktop access, and so a new VNC server, called wayvnc, is being used instead of RealVNC. This is a bit more restrictive in terms of the client applications which can connect to it — we have had good results with the TigerVNC client, available here.
- There is also currently a regression with the RealVNC server itself, which is still used in Bookworm on older Raspberry Pi models which don’t yet run Wayland. The 64-bit version works fine, but the 32-bit version is not currently compatible with Bookworm — we are waiting for an update from RealVNC. In the meantime, if you do need remote desktop access on a Raspberry Pi Zero, 1, 2, or 3, we recommend sticking with Bullseye for the time being.
A few programs have been removed from Recommended Software and the full image:
- The SenseHAT Emulator is not at present compatible with Bookworm — this is being worked on now, and we hope to have it back in a few weeks’ time.
- The Magnifier accessibility tool doesn’t work with Wayfire, but Wayfire already has its own (better) magnifier built in — just hit ctrl-alt-M to turn it on and off.
- The BlueJ and Greenfoot Java IDEs are incompatible with Wayland, and Sonic Pi is incompatible with PipeWire — these are third-party programs, so have been removed until their developers have updated them.
Just in case…
All these changes are designed to bring Raspberry Pi OS more into line with what other Linux distributions are doing — many are making, or have already made, the switch to Wayland, PipeWire and NetworkManager. This, then, gives us a good platform for future development, with the reassurance that our desktop is sitting on the same underlying components as most of the rest of the desktop Linux ecosystem.
While we have been using Wayland and PipeWire internally for nearly a year now, the sheer scale of the changes means that, in some specific usage scenarios, one or the other may cause problems. For this reason, the Advanced Settings menu in raspi-config includes options to re-enable the old X11/Openbox display system and PulseAudio. You shouldn’t need to use these, but the option is there just in case!
How to get it
We have always said that for a major version upgrade, you should re-image your SD card and start again with a clean image. In the past, we have suggested procedures for updating an existing image to the new version, but always with the caveat that we do not recommend it, and you do this at your own risk.
This time, 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. The only way to get Bookworm is either to create an SD card using Raspberry Pi Imager, or to download and flash a Bookworm image from here with your tool of choice.
