Plymouth Theme Customization

1. Introduction

Plymouth is a tool for customizing the splash screen upon boot and shutdown. To do this, it employs theming with many themes available online. While the basic installation and configuration of both Plymouth are fairly straightforward, sometimes we might want to make modifications to existing themes or create one of our own.

In this tutorial, we explore some advanced theme options of the Plymouth splash screen customization. First, we briefly check the available themes, the theme path, and how to change the default theme. After that, we go through a full example of creating a new theme.

We tested the code in this tutorial on Debian 12 (Bookworm) with GNU Bash 5.2.15. Unless otherwise specified, it should work in most POSIX-compliant environments.

2. Selecting Boot Screen

To ensure we have the desired theme selected, we can employ –update-alternatives:

$ update-alternatives --config default.plymouth

After issuing the command, we should see all currently installed themes, the default theme path, and a choice prompt:

There are 2 choices for the alternative default.plymouth (providing /usr/share/plymouth/themes/default.plymouth).

  Selection    Path                                                             Priority   Status
------------------------------------------------------------
  0            /usr/share/plymouth/themes/bgrt/bgrt.plymouth                     110       auto mode
  1            /usr/share/plymouth/themes/bgrt/bgrt.plymouth                     110       manual mode
* 2            /usr/share/plymouth/themes/basic/basic.plymouth                   166       manual mode
Press <enter> to keep the current choice[*], or type selection number:
$ update-initramfs -u

Notably, we can see that, in this case, the themes directory is /usr/share/plymouth/themes/, which is important for the steps below.

Still, there might not be a theme locally or online that fully suits are needs. In such cases, we can opt to either customize or create our own arrangement.

3. Theme Creation and Modification

Although we can create a new theme from scratch, this is rarely done. Instead, we can use an existing theme as the project skeleton. Notably, this isn’t necessary, so we can just use any available theme for reference if desired.

3.1. Theme Template

Many Linux distributions use Plymouth and most of those come with a custom theme. For example, Ubuntu offers both the graphical ubuntu-logo and the text-based ubuntu-text themes.

In our case, we use a minimalistic theme. Since all themes comprise text files and images, we can freely copy any specific one and trim it, regardless of its complexity.

3.2. Copy Theme Skeleton

To begin with, we get a copy of the base theme from the configured themes path or an online source:

$ git clone https://github.com/barskern/plymouth-theme-simple-image

Let’s enter and inspect the resulting directory:

$ cd plymouth-theme-simple-image
$ ls
img.png  LICENSE  README.md  simple-image.plymouth  simple-image.script

In general, a Plymouth theme has several main files:

• .plymouth: main theme file
• .script: scripts with the core of the theme mechanics
• .grub: bootloader script with terminal and other configurations
• graphical resources such as img.png

Now, we can begin transforming.

3.3. Rename Theme

Since the theme definition files currently have the name of the original, let’s rename them accordingly:

$ mv simple-image.plymouth xorpig.plymouth
$ mv simple-image.script xorpig.script
$ mv img.png main.png

Then, within the .plymouth theme file, we can change the references accordingly.

Let’s see the original first:

$ cat xorpig.plymouth
[Plymouth Theme]
Name=Arch Linux Simple Image
Description=This is a plymouth theme which simply displays an image
ModuleName=script

[script]
ImageDir=/usr/share/plymouth/themes/simple-image
ScriptFile=/usr/share/plymouth/themes/simple-image/simple-image.script

Now, we can make some basic and fairly self-explanatory changes:

$ cat xorpig.plymouth
[Plymouth Theme]
Name=XOR Pig Theme
Description=Basic image theme
ModuleName=script

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

In this case, we modify the Name, Description, and paths. Notably, the paths may need to change further in case our default theme directory doesn’t match the one within the theme definition.

3.4. Modify Scripts

As also defined in the ModuleName field in the .plymouth file, the theme is mainly focused in the .script file:

$ cat xorpig.script
image = Image("img.png");

pos_x = Window.GetWidth()/2 - image.GetWidth()/2;
pos_y = Window.GetHeight()/2 - image.GetHeight()/2;

sprite = Sprite(image);
sprite.SetX(pos_x);
sprite.SetY(pos_y);

fun refresh_callback () {
  sprite.SetOpacity(1);
  spr.SetZ(15);
}

Plymouth.SetRefreshFunction (refresh_callback);

Here, we can see the original, which loads the image by its old filename and performs several actions:

1. calculate the center of the screen, shifted by half the width of the image
2. create an object from the image and place it at the center
3. define a function that controls the opacity and Z position
4. set the defined function as the refresh actions

Of course, we need to change the image filename reference at the very least. The rest depends on the needs and requirements.

3.5. Extend Theme

As we can already see, themes comprise a definition file, scripts, and resources.

Effectively, we can extend a theme by modifying existing Plymouth scripts or commands or creating new ones.

Further, graphics files are usually simple images, which the scripts animate. Thus, we can replace or add to the graphics.

Some themes come with a bootloader configuration as well. It serves to further customize the experience by making changes to the boot settings. Adding one isn’t a requirement, but a bootloader file may aid with some low-level changes.

3.6. Install Theme

After making all the modifications and including additions, we should be ready to copy the new theme to the theme directory:

$ cp --recursive xorpig/ /usr/share/plymouth/themes/

At this point, we should be able to select our new theme as the default and see it in action. Alternatively, we can test the theme by directly controlling the plymouthd daemon and plymouth client:

$ plymouthd && plymouth --show-splash && sleep 5 && killall plymouthd

Either way, we should be able to see the results of our modifications.

4. Summary

In this article, we talked about Plymouth theme customization.

In conclusion, although there are many free Plymouth themes available online, knowing how to customize them or create new ones goes a long way to enable personalization.