Bookworm - Q-engineering
Go to content
Bookworm on Raspberry Pi 5

Bookworm on Raspberry Pi.

Last updated: January 25, 2024


The new Debian "Bookworm" OS is now available on the Raspberry Pi. There are some things you need to know about this new version.

Firstly, Bookworm supports the Wayland video engine instead of the 'old' X11. Just being released, not every supplier has adapted its software. Most noteworthy is the RealVNC interface. Undoubtedly, they come up with a good solution shortly. For now, there is a workaround for the 64-bit OS version.

Another point is the Python 3.11 version found in Bookworm. Not all packages have installation wheels for a 3.11, aarch64 machine.
For instance, installing TensorFlow with Bazel is a nightmare. There is an avalanche of unmet dependencies.
Also, Python 3.11 demands virtual environments when using the pip installer, something not everyone likes.

The Wayland video engine has a stricter security protocol. At the time of writing, RealVNC is working on an update to comply with the new rules. For now, there are two workarounds.
Adjust the Wayland security level.
The first workaround is adjusting the security level.

Firstly, make sure you have enabled VNC in your Raspberry Pi Configuration.


Next, disable the authorization in the configuration file with the following commands.
# alter the VNC config file
$ cd ~
$ sudo nano .config/wayvnc/config
# inside the file
# save and close with keys
<Ctrl>+<X>, <Y>, <Enter>


After a reboot, you can access your Raspberry Pi with RealVNC in the usual way. The only difference is the lack of file transfers (and the icon in the Taskbar).
Restoring the X11 engine.
The second workaround is restoring X11. Perhaps it sounds a bit destructive, but that is not the case. If you are using the RPi for computing and not for high-quality video editing, there is no harm done whatsoever in returning to X11 for now. The sideshow below guide you through the steps.
You can access the Raspberry Pi desktop on a remote computer and have the file transfer working again.

File transfer VNC

Virtual environments.

Bookworm has Python 3.11 as the default Python version, the first version demanding the use of virtual environments.
What are virtual environments?
A virtual environment is a Python tool for dependency management and project isolation. It allows Python site packages (third-party libraries) to be installed locally in an isolated directory, instead of globally (i.e. as part of a system-wide Python).
An example. You install Tensorflow with a pip command. During installation, Tensorflow will install Numpy. Sometime later, you want to install PyTorch on your Pi as well. In turn, Pytorch may install a newer version of Numpy, causing Tensorflow to have serious compatibility errors.
Using separate virtual environments would leave the Tensorflow Numpy untouched. It would install another instance in the PyTorch virtual environment.

Another potential conflict can be the different installation between apt and pip.
Who hasn't installed OpenCV two or three times? First with sudo apt-get install and the second or third time unnoticed by means of a pip command executed by the requirements of an installation wheel. It causes nightmarish problems because it is no longer clear who owns which version.

Here, you have the strengths and weaknesses in one sentence. To maintain secure environments, copies of software packages are on your SD card. Each environment can have its own Numpy, OpenCV and MatPlot. If you have a large SSD card, that's no problem. A small SD card can quickly fill up with (almost) identical software. That is why we never use the virtual environment on a Raspberry Pi. Instead, we swap SD cards. It is up to you.

As said, Bookworm demands the use of virtual environments. If you try to install some software without a virtual environment, you get the next error.

Bookworm pip error

You have two options: create a virtual environment or switch the entire control mechanism off.
Disable the control
By remaining the file responsible for the check, you disable the functionality.
$ sudo mv /usr/lib/python3.11/EXTERNALLY-MANAGED /usr/lib/python3.11/EXTERNALLY-MANAGED.old
If you want to enable the check again, restore the file name.
Or create a virtual environment.
The second method follows the suggestions of the Python people: make the environment and don't mesh around.
When using deep learning frameworks, this method certainly has advantages. These software packages come with a lot of dependencies, which can easily conflict with one another. Containing in a virtual environment solves all your problems once and for all.

Step one is some administration. We only use Python 3 because the support of Python 2.7 has stopped at the beginning of 2020. You have first to determine your Python 3 version and location. This location must be placed in the (hidden) ~/.bashrc file. The easiest way is a direct injection at the end of the file. You don't have to use an editor like nano or leafpad now.
# get version
$ python3 --version
# get location
$ which python 3.9
# merge VIRTUALENVWRAPPER_PYTHON=location/version
$ echo "export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python" >> ~/.bashrc
# reload profile
$ source ~/.bashrc
The Python location in the above commands was /usr/bin/python. This location is passed as an argument in the echo command.


The next step is installing the virtual environment software. This can be done with the following commands.
$ sudo apt-get install python3-virtualenv
$ sudo apt-get install python3-virtualenvwrapper
The last step is again some administration in the ~/.bashrc file, followed by a re-activation.
With the command mkvirtualenv, a virtual environment is set up for the OpenCV installation.
$ echo "export WORKON_HOME=$HOME/.virtualenvs" >> ~/.bashrc
$ echo "source /usr/local/bin/" >> ~/.bashrc
$ source ~/.bashrc
$ mkvirtualenv cv480
# to quit working in cv480
(cv480) $ deactivate
# to activate cv430 the next time
$ workon cv480

Your screen will be something like this.


One tip: never use sudo in a virtual environment: it leads to permission conflicts.
Back to content