Plymouth theming guide (part 1)

Judging by the many forum postings and articles, many people do enjoy a nice boot splash and there is a real desire to customise their spin or even the individual machine to their preferred theme. In this guide I will try and show you how to make your own custom splash, walking though the process of viewing, changing and installing. Even if you are a Linux novice, you should be able to follow the steps without much trouble. This guide assumes a Fedora system, although there should be very few changes between the different installations.

Set-up

Obviously you can view plymouth running by turning on your computer, but that does get rather tiresome if you wish to test frequently. Without restarting your machine, there are three sensible methods of testing plymouth: using a  victim machine, using a virtual victim machine or using the X11 plugin.

Victim machine

This is the easiest method, although it does require a second physical machine to work with.

If you do not have a KMS compatible system, then you will need to add vga=0x318 to your kernel line. This pushes the console to a VESA graphical mode. The 0x318 actually stipulates 1024x768x32bit mode. To see all the modes and find one most suitable for you, add vga=askme and a list will appear (don’t forget the 0x).

SSH into the machine as root (yes you do need to be root). The splash will be tested on tty1, but tty1 has two problems: there is an X session running on it and if you quit that, getty will start and capture keyboard events. To turn off getty on tty1, edit /etc/event.d/tty1 an comment out all the start and stop lines with a hash.

#start on stopped rc2
#start on stopped rc3
#start on stopped rc4

#stop on runlevel 0
#stop on runlevel 1
#stop on runlevel 6

Then drop to init level 3, which kills X and brings you to an empty console, by running init 3. Now install all the themes you wish to try out:

yum install plymouth\*

This is how to do this in Fedora, you should know the way to do this in your distro already.

Virtual victim machine

The alternate to using a physical machine is to use a virtual one. Both VMWare and QEmu work very well. You will have to do an OS install on the virtual machine. These do not yet support KMS (support is coming soon apparently), so you will need to add the vga parameter on the kernel line. The setup is exactly the same as  one for a physical victim machine.

X11 plugin

This method allows you to execute plymouth within X. This is the preferred testing method BUT it can crash your X if you accidentally pick a text theme. It also does require you to compile your own version of plymouth to get the x11 renderer. As root get the latest git checkout:

git clone git://anongit.freedesktop.org/plymouth

Next configure and compile it:

> cd plymouth
> ./autogen.sh --prefix=/usr/ --with-system-root-install
> make
> make install

Now it is installed, make sure you have the DISPLAY set correctly so even if you run as root, it can connect to your X session and display the windows.

plymouth-x11

When you run it using the directions below, you will notice you get two screens which allows you to test the behaviour of a two monitor setup.

Viewing

Now you have the system set up, you can manually execute plymouth to examine a theme. First, as root, start the plymouth daemon (plymouthd lives in /sbin/ so make sure you have that in your path):

> plymouthd

Now it is executing, you can control it using the plymouth program. To show the splash run:

> plymouth --show-splash

This should display the splash.

plymouth_charge

To quit, execute

> plymouth quit

The splash should then quit and the terminal return to its text mode. You may have noticed the progress did not advance very quickly. The progress is estimated using events, based on the event arrival time of the previous boot. To show the splash for 10 seconds and watch the progress moving execute the following one-liner:

> plymouthd; plymouth --show-splash ; for ((I=0; I<10; I++)); do plymouth --update=test$I ; sleep 1; done; plymouth quit

There are several themes installed on your system. To get the full list run:

> plymouth-set-default-theme --list

To change to any of these themes replace –list with the theme name e.g.:

> plymouth-set-default-theme spinfinity

Now you can examine any theme you wish. But what if you don’t like any of them?

Theme editing

It is important to understand the difference between a theme and a plugin. A theme uses a plugin and stipulates some parameters the plugins uses. This information is stored in the directories under /usr/share/plymouth/themes/. Each directory has a .plymouth file which describes the theme, stating the plugin it uses and any parameters the plugin allows to be set. To create a new theme, simply copy an entire directory to a new name, rename the .plymouth file to the new name, and update its contents. In addion, you can now also change the images that your new custom theme uses.

This is sufficient if you wish to recycle one of the already present plugins. For more customisability you can write your own plugin in C which is, to be honest, not very easy. The much simpler alternative is to use the script plugin and write a script to describe the theme, and that is what I shall be describing in the next post.

    • oskude
    • January 7th, 2010

    very nice tutorial, thanks for doing it!

    just wanted to note, if you need to get the git over http (like when bored at work;), this seems to work:
    git clone http://anongit.freedesktop.org/git/plymouth

  1. Thank you very much for this great tutorial!

    • Astral
    • May 24th, 2010

    Just wanted to say .. .plymouth files are in:

    /lib/plymouth/themes

    • Yes, on Ubuntu they are in /lib/plymouth/themes. On other systems it is /usr/share/plymouth/themes.

    • vikas
    • May 31st, 2010

    i wanna ask u that is it possible to change the back ground of the splash to any animated .gif

    • No, only PNG images are allowed. You can make animations by loading a set of images and making each visible (opacity set to 1 or 0) one after another.

    • Anitha
    • September 27th, 2010

    Can i show paused progress bar for some time and then unpaused progress bar for some time in plymouth spinfinity?

    • You can run
      plymouth pause-progress
      and
      plymouth unpause-progress

        • Anitha
        • October 1st, 2010

        Brej,

        Thanks for your reply..
        If we run plymouth pause-progress command, upto what time, the progress bar is in paused state? If i want to set the pause-progress for 30 sec and after that unpaused bar how can i use the commands?

  2. thanks for this great tutorial!

    • andrez
    • October 27th, 2010

    I am trying to create a new theme by following your tutorial. Problem the command you provided:

    plymouth-set-default-theme –list

    seems not to be running on Kubuntu 10.10. By the way, the bootsplash with plymouth seems not to be working properly. Can’t spot any progress since usplash either.

  3. Hi! I’m Alex one of developers of Burg-Manager for Ubuntu. We are creating a super-boot-manager that can manage burg, grub2 and plymouth.
    I’ve read much tutorial about Plymouth. All this tutorial uses this command to show Plymouth preview:

    sudo plymouthd
    sudo plymouth –show-splash

    But it open 2 preview windows: a small one and a big one.
    There is a way to open only a preview window ?

    • johny b
    • July 13th, 2011

    When I run “./autogen.sh –prefix=/usr/ –with-system-root-install”, I get a whole lot of errors and a message saying “autoreconf: automake failed with exit status: 1″. Does anybody know what’s going on?

    • chris
    • July 25th, 2011

    hello,
    can you tell me how i make a Wallpaper to a Theme,please?

    • JL Griffin
    • December 7th, 2011

    HI, I am attempting to edit the glow theme… its a pie type progress bar which fades to a bright orb and then down into: ©BIZCOM. I have edited all the throbber images to reveal my logo and then “V. 1.0″ . I can get this working fine, but i want it to display a background image with my logo instead of ubuntu’s murky purple colored background image. I followed several tutorials and added a script file which should in theory work properly, but it doesnt. Any ideas? I could send you a tar.gz with all the files for my theme in it if you’d like. Thanks in advance,

    -JL Griffin

    • Orcus
    • July 1st, 2012

    Nice tutorial, thanks. But I would like to point out, that X11 renderer plugin in part of plymouth-devel package on Fedora 17, don’t know about other releases. So you don’t have to compile it, only install that package.

    • Paul G
    • March 9th, 2014

    This may be a bit off topic but after grub loads plymouth begans correct? there is some error message that flashes up really fast. How can I edit plymouth to pause for a few seconds in order for me to read the error?

    Thank you,