Setting Up a Custom Splash Screen on Raspberry Pi 5

Introduction#

When you deliver software running on a Raspberry Pi as a finished “product,” the appearance of the boot sequence—from power-on until the application starts—matters more than you might expect.

The usual progression of a rainbow test pattern, white kernel messages scrolling across a black screen, the Raspberry Pi OS desktop, and finally your application feels a lot like watching a DIY PC being assembled. In my view, it can quickly break the end user’s sense of immersion.

This article explains how to replace the boot visuals on a Raspberry Pi 5 running the 64-bit edition of Raspberry Pi OS Bookworm. We will work through hiding the bootloader-stage graphics, creating a custom Plymouth splash, and setting up a kiosk environment.

Test environment#

Note: Wayfire was the default when Bookworm was first released, but updates from October 2024 onward made labwc (Wayland) the default compositor on the Pi 4 and Pi 5. Due to hardware limitations, Pi 3 and earlier models may still use X11 (LXDE) or Wayfire configurations. This article assumes Wayland, although the essential steps are nearly the same on X11.

1. Deciding which parts of the boot sequence to replace#

The Raspberry Pi 5 boot process can be divided roughly into the following stages:

[Power on]
   │
   ▼
(1) Bootloader (EEPROM)         ← Raspberry Pi logo / rainbow test pattern
   │
   ▼
(2) Kernel loading              ← On Pi 5, the bootloader loads the kernel directly
                                   (Pi 4 and earlier use start*.elf)
   │
   ▼
(3) Linux kernel startup        ← White kernel messages / four Raspberry Pi logos
                                   in the upper-left corner
   │
   ▼
(4) systemd (init)              ← Plymouth splash
   │
   ▼
(5) Login                       ← Bookworm normally uses getty@tty1 autologin
                                   (lightdm/greetd are not installed by default)
   │
   ▼
(6) Desktop (labwc)             ← Wallpaper and panel
   │
   ▼
(7) User application

The difficulty of creating a branded boot screen depends greatly on which stages you replace.

There is little room to customize the firmware stages in (1) and (2), so in practice it is best to limit changes there to hiding the rainbow screen. You can suppress almost all kernel messages in stage (3) through cmdline.txt, while Plymouth in stage (4) is the main tool for the custom splash in this guide. If you also want to hide the desktop in stages (5) and (6), avoid starting tty1 autologin or the desktop and run only your application on a Wayland compositor.

In short, controlling stages (1), (3), and (4) lets you present an almost completely custom visual sequence from power-on until your application starts. That is our goal here.

2. Hiding and replacing bootloader-stage graphics#

Hide the rainbow test pattern#

The rainbow screen initially shown by the firmware—a test pattern used to check the display connection—can easily be disabled in config.txt.

sudo nano /boot/firmware/config.txt

Add the following line at the end:

disable_splash=1

The rainbow screen will no longer appear.

Hide the firmware logos (four Raspberry Pi icons)#

The four Raspberry Pi icons that appear in the upper-left corner immediately after the Linux kernel starts can be hidden with the logo.nologo option in cmdline.txt, which we will edit in the next section. Controlling them through the kernel parameters is the practical approach.

About displaying a static splash image#

Some online guides claim that placing splash.png under /boot/firmware/ will turn it into a bootloader-stage logo. This behavior is not supported by the standard Raspberry Pi OS firmware and generally does not work on a Pi 5 running Bookworm. Fully customizing the bootloader-stage visuals would require a custom EEPROM build, which is not very practical. We will therefore leave this stage black and display the logo with Plymouth instead.

3. Suppressing kernel messages#

Edit /boot/firmware/cmdline.txt so that kernel messages are not shown on the display.

sudo nano /boot/firmware/cmdline.txt

This file must remain on a single line, so do not insert a line break. Append the following options to the existing parameter list:

quiet splash logo.nologo loglevel=0 vt.global_cursor_default=0 console=tty3

Each option has the following purpose:

After making the change, run sudo reboot and confirm that the white kernel messages no longer scroll across the screen.

[Screenshot needed: comparison of the boot screen before and after changing cmdline.txt]

4. Creating a custom splash with Plymouth#

This is the main part of the setup.

Install Plymouth#

sudo apt update
sudo apt install -y plymouth plymouth-themes

Plymouth itself is usually already present on Bookworm as a dependency. Installing plymouth-themes adds several example themes that are useful references when creating your own.

Create a custom theme#

Themes are stored in /usr/share/plymouth/themes/<name>/. We will create one named mybrand.

sudo mkdir -p /usr/share/plymouth/themes/mybrand
cd /usr/share/plymouth/themes/mybrand

Place your logo image here as logo.png. It will be centered on the display; for a 1920 × 1080 screen, an image around 512 pixels square is easy to work with. We will also add the mybrand.plymouth and mybrand.script files described below.

sudo cp /path/to/your/logo.png ./logo.png

The .plymouth file#

Create mybrand.plymouth with the following content:

[Plymouth Theme]
Name=mybrand
Description=Brand splash for Raspberry Pi 5
ModuleName=script

[script]
ImageDir=/usr/share/plymouth/themes/mybrand
ScriptFile=/usr/share/plymouth/themes/mybrand/mybrand.script

The .script file (minimal example)#

Create mybrand.script with the following content. This minimal setup displays a single logo in the center. Plymouth Script is a proprietary, C-like scripting language, so any syntax highlighting should be treated as approximate.

# Fill the background with black
Window.SetBackgroundTopColor(0.0, 0.0, 0.0);
Window.SetBackgroundBottomColor(0.0, 0.0, 0.0);

# Center the logo
logo.image = Image("logo.png");
logo.sprite = Sprite(logo.image);
logo.sprite.SetX(Window.GetWidth() / 2 - logo.image.GetWidth() / 2);
logo.sprite.SetY(Window.GetHeight() / 2 - logo.image.GetHeight() / 2);

To add a progress bar or spinner, you can use callbacks such as Plymouth.SetBootProgressFunction to animate sprites. A single static image is enough for a first version.

Register and select the theme#

Use update-alternatives to add the theme to the list of default Plymouth themes, then select it:

sudo update-alternatives --install \
  /usr/share/plymouth/themes/default.plymouth default.plymouth \
  /usr/share/plymouth/themes/mybrand/mybrand.plymouth 200

sudo plymouth-set-default-theme -R mybrand

The -R option regenerates the initramfs. Do not forget it, or the change will not take effect—this has caught me out more than once.

Reboot the system. If the logo appears in the center between the start of shutdown and the desktop appearing, the setup is working.

5. Tips for testing#

Rebooting after every adjustment quickly becomes tedious. Plymouth provides a debugging command that displays the splash in the current session:

# Start Plymouth for testing, show the splash for five seconds, then exit
sudo plymouthd ; sudo plymouth --show-splash ; sleep 5 ; sudo plymouth quit

While this command runs, the active splash theme takes over the display. You can repeat the cycle of editing .script, running the command, and checking the result without rebooting. It can also be run over SSH, which makes it convenient to change only the HDMI display.

The splash may occasionally fail to render on the first attempt. If that happens, start plymouthd with --debug --debug-file=/tmp/plymouth.log to write a log and make the cause easier to trace.

Running the test during a Wayland session can cause visual glitches because Plymouth competes with the compositor for the display. This only affects testing. During the actual boot sequence under systemd, Plymouth renders on its own, so it is not a problem.

6. Starting only the application without showing the desktop#

At this point the splash covers the boot process, but if the desktop appears immediately after Plymouth exits, the experience still feels interrupted.

For a product, the simplest solution is often to skip the desktop and launch only your application in full-screen mode. Based on my experience with Bookworm and Wayland, there are roughly three practical options:

• cage: A Wayland compositor designed for a single application. It can be installed with apt install cage and is the most straightforward choice for a kiosk. Its options differ between versions, so check the available flags with cage --help after installation.
• Launch labwc directly: Start labwc from a tty and use its autostart configuration to launch only your application. Because this is the same compositor used by Raspberry Pi OS, compatibility tends to be good.
• X11 + matchbox-window-manager: A traditional combination that remains useful when staying on X11 is acceptable.

The following systemd service is a minimal example using cage:

# /etc/systemd/system/kiosk.service
[Unit]
Description=Kiosk app
After=systemd-user-sessions.service plymouth-quit-wait.service
[email protected]

[Service]
Type=simple
User=pi
PAMName=login
TTYPath=/dev/tty1
StandardInput=tty
StandardOutput=journal
StandardError=journal
ExecStart=/usr/bin/cage -- /usr/local/bin/your-app

[Install]
WantedBy=graphical.target

Adding After=plymouth-quit-wait.service makes cage wait until Plymouth has completely closed, minimizing screen flicker. Standard Raspberry Pi OS setups often use getty@tty1 for autologin. In raspi-config, select Boot Options → Desktop / CLI → Console to disable autologin and the automatic launch of labwc, preventing the desktop from briefly appearing.

[Screenshot needed: transition directly from the Plymouth splash to the application after boot]

7. Conclusion#

The Raspberry Pi 5 boot display can be confusing at first because several different stages are involved. The essential approach is simple: hide the bootloader’s rainbow screen and logos, silence kernel messages through cmdline.txt, create the visible experience with Plymouth, and use a kiosk setup so the desktop is never shown.

Replacing the Plymouth theme has almost no effect on the actual boot time because it only changes the rendering layer. If faster startup is the goal, you will need a separate round of optimization using systemd-analyze blame to identify and address slow units. I hope to cover that in another article.

A polished boot sequence makes the same hardware feel much more like a finished product, so this is a worthwhile step for anyone using a Raspberry Pi in an embedded system.

References#

www.raspberrypi.com

www.raspberrypi.com

www.raspberrypi.com

www.raspberrypi.com

Plymouth - ArchWiki

wiki.archlinux.org

www.freedesktop.org

www.freedesktop.org

systemd.service

www.freedesktop.org

Cage: the Wayland kiosk

Cage: the Wayland kiosk

Jente Hidskes' website