3 Things to Look Out for when working with the Raspberry Pi OS

In the previous post, we learned to write our first line of code on a Raspberry Pi 5. I bought my Raspberry Pi 5 last year and didn't touch it until recently. While planning to use this Raspberry Pi to build some cool robotics and networking projects, I soon started facing some obstacles with the operating system itself. So, in this post, I want to share an overview of the challenges I've faced while working on the Raspberry Pi 5, along with solutions that have worked for me. I hope this will also help anyone who is struggling with their own Raspberry Pi 5 programming. Table of Contents The Raspberry Pi OS X11 and Wayland Identifying whether your Raspberry Pi OS is running X11 or Wayland Taking screenshots on the Raspberry Pi OS Screen Blanking Text-only Boot Closing Thoughts The Raspberry Pi OS Now before addressing the challenges, we must understand a few key aspects of the operating system itself. Raspberry Pi OS is a free and open-source, Linux-based operating system, a port of Debian designed to run on a Raspberry Pi SBC. The version of Pi OS I am running on my Raspberry Pi is based on Debian 12 which I can confirm by typing the following command in a terminal: hostnamectl | grep -E "Operating System|Kernel|Architecture" Which will output: Operating System: Debian GNU/Linux 12 (bookworm) Kernel: Linux 6.6.74+rpt-rpi-2712 Architecture: arm64 With the release of Bookworm in 2023, X11 was replaced by Wayland, which became the default operating mode for Raspberry Pi 4 and 5. "With the release of Bookworm in 2023, we replaced mutter with a new dedicated Wayland compositor called wayfire and made Wayland the default mode of operation for Raspberry Pi 4 and 5, while continuing to run X on lower-powered models." — Simon Long from "A new release of Raspberry Pi OS" X11 and Wayland X Window System or X11 for short, is the traditional display server protocol that has been used on Linux for decades. On the other hand, Wayland is a modern display server protocol that was designed to replace X11. Wayland also aimed to be to more efficient, secure, and easier to develop and maintain than X11. In contrast to X11, Wayland employs uses a compositor-based model where the compositor controls the entire display, including rendering windows and graphics. This results in a layer of incompatibility among application packages. Identifying whether your Raspberry Pi OS is running X11 or Wayland As mentioned earlier, some X11 applications and utilities are incompatible with the Wayland protocol, and the same is true in reverse. When working on a project that directly uses system commands, it is essential to know whether we are using X11 or Wayland to ensure our code is compatible across different environments. Now, we can use our trusty grep command to search for the session type in the environment variables. To do so, open a new terminal from your desktop and type the following: env | grep "XDG_SESSION_TYPE" If you are using Wayland, this will yield, XDG_SESSION_TYPE=wayland If you are using X11, you will see, XDG_SESSION_TYPE=x11 Taking screenshots on the Raspberry Pi OS Raspberry Pi OS offers two distinct command-line tools to take screenshots. One is called grim and the other is called scrot. grim is only compatible with a Wayland environment as it was designed to capture images from a Wayland compositor. On the other hand, scrot is only compatible with an X11 environment. So if we try to use the scrot command in a Wayland environment, it will produce a completely black image!

Mar 25, 2025 - 22:03

3 Things to Look Out for when working with the Raspberry Pi OS

In the previous post, we learned to write our first line of code on a Raspberry Pi 5. I bought my Raspberry Pi 5 last year and didn't touch it until recently. While planning to use this Raspberry Pi to build some cool robotics and networking projects, I soon started facing some obstacles with the operating system itself.

So, in this post, I want to share an overview of the challenges I've faced while working on the Raspberry Pi 5, along with solutions that have worked for me. I hope this will also help anyone who is struggling with their own Raspberry Pi 5 programming.

The Raspberry Pi OS
- X11 and Wayland
- Identifying whether your Raspberry Pi OS is running X11 or Wayland
Taking screenshots on the Raspberry Pi OS
Screen Blanking
Text-only Boot
Closing Thoughts

The Raspberry Pi OS

Now before addressing the challenges, we must understand a few key aspects of the operating system itself.

Raspberry Pi OS is a free and open-source, Linux-based operating system, a port of Debian designed to run on a Raspberry Pi SBC. The version of Pi OS I am running on my Raspberry Pi is based on Debian 12 which I can confirm by typing the following command in a terminal:

    hostnamectl | grep -E "Operating System|Kernel|Architecture"

Which will output:

Operating System: Debian GNU/Linux 12 (bookworm)
          Kernel: Linux 6.6.74+rpt-rpi-2712
    Architecture: arm64

With the release of Bookworm in 2023, X11 was replaced by Wayland, which became the default operating mode for Raspberry Pi 4 and 5.

"With the release of Bookworm in 2023, we replaced mutter with a new dedicated Wayland compositor called wayfire and made Wayland the default mode of operation for Raspberry Pi 4 and 5, while continuing to run X on lower-powered models."
— Simon Long from "A new release of Raspberry Pi OS"

X11 and Wayland

X Window System or X11 for short, is the traditional display server protocol that has been used on Linux for decades. On the other hand, Wayland is a modern display server protocol that was designed to replace X11. Wayland also aimed to be to more efficient, secure, and easier to develop and maintain than X11.

In contrast to X11, Wayland employs uses a compositor-based model where the compositor controls the entire display, including rendering windows and graphics. This results in a layer of incompatibility among application packages.

Identifying whether your Raspberry Pi OS is running X11 or Wayland

As mentioned earlier, some X11 applications and utilities are incompatible with the Wayland protocol, and the same is true in reverse. When working on a project that directly uses system commands, it is essential to know whether we are using X11 or Wayland to ensure our code is compatible across different environments.

Now, we can use our trusty grep command to search for the session type in the environment variables. To do so, open a new terminal from your desktop and type the following:

    env | grep "XDG_SESSION_TYPE"

If you are using Wayland, this will yield,

    XDG_SESSION_TYPE=wayland

If you are using X11, you will see,

    XDG_SESSION_TYPE=x11

Taking screenshots on the Raspberry Pi OS

Raspberry Pi OS offers two distinct command-line tools to take screenshots. One is called grim and the other is called scrot. grim is only compatible with a Wayland environment as it was designed to capture images from a Wayland compositor.

On the other hand, scrot is only compatible with an X11 environment. So if we try to use the scrot command in a Wayland environment, it will produce a completely black image!