Unsupported Version
This article applies to an unsupported version of Ubuntu. More info...

How do I customize USplash?

Edgy USplash

The implementation for usplash changed from Dapper to Edgy (6.06 - 6.10) and therefore the technique also changed for adjusting it. The following is taken directly from /usr/share/doc/usplash-dev/examples/README. In Gutsy, you can find the same file at /usr/share/doc/libusplash-dev/examples/README. Karmic (9.10) uses an X-based splash screen along with USplash.

Edgy USplash README Information from usplash-dev

How to create usplash themes

Usplash in its current incarnation allows for simple and advanced themes. I'll start with explaining the basics of a theme and will introduce the more advanced topics later. I do assume that the reader has basic C programming knowledge and knows what a Makefile is for.

A basic theme

A basic theme consist of a background picture and color/position definitions for various elements. The usplash-theme.h file lists all of them (ignore the function pointers for now). If you specify only a background image and color/position variables, usplash will take care of drawing a basic progress bar and the text. The included usplash-testcard-theme.c is such a basic theme

The image you use should have max. 256 colors. The resolution is up to you, but keep in mind that usplash will use the resolution of the image without checking whether your display supports it. For themes that are to be default for many people, I recommend choosing no higher than 800x600. The utility 'pngtousplash' can be used to convert an image to usplash-usable C code. The example-theme directory contains a complete them that builds out-of-source. Inspect its Makefile to see how to put the pieces together. If you intend to create a package, make sure to Build-Depend on usplash-dev, which contains pngtousplash and the necessary header files. In Hardy this package has been renamed to libusplash-dev.

You should always allow your theme to display text, the INPUT function of usplash will display text, even when not running verbose.

Themes have a ratio field where you can specify either USPLASH_4_3 if the image is a true 4:3 image or 16:9 if the image is a 16:9 image, scaled to 4:3. The image MUST be a 4:3 image, because usplash can only handle 4:3 video modes currently.

Optional 1: Custom font

You can include a custom font. You will need to link it into your theme .so file and set the .font field in the theme structure. The example theme supplies a custom font, so once again: look there. The font should be a bdf font, converted with bdftousplash.

Optional 2: Custom drawing functions and animation

Themes can override the functions called for displaying the progress bar and/or text. This can be used to create better looking progress bar. If you supply a custom progress bar, you're sort of forced to implement custom animations too, since the animation code is also used for displaying a pulsating progress bar.

25 times per second, the animation function is called. This function has one argument: whether the progress bar is currently pulsating or not. This allows you to create animated themes as well as simply doing a better looking progress bar.

If you override the custom drawing functions, please make sure that any images you use, use the exact same palette as the background image. You can do this by creating one big image containing all components and then cutting out the respctive images or by following the instructions on http://carol.gimp.org/gimp/resources/palettes/howto.html

For now, you should not override draw_text, because the INPUT function of usplash will not use it and thus the txt will look odd in you theme.

The included example theme uses custom animation for the progress bar, so once again it can be used as an example.

Optional 3: Multiple themes in one file

Usplash theme librarys can contain multiple themes in a linked list. Each theme has a next pointer, which should either be NULL or point to another theme in the same file. The example theme includes the same theme at three different resolutions.

The first theme in the list should still be called usplash_theme and it should be the fallback variant of your theme, lowest resolution and 4:3 scale. This because usplash will use the first theme in case no favorable resolution was specified on th command line.

The theme selection will also take the ratio of your screen into account, so it will favor a low-res 16:9 variant over a high-res 4:3 variant if you have a 16:9 screen.

-- Sept. 6 2006 Dennis Kaarsemaker <dennis@ubuntu.com>

Dapper USplash

Before starting, make sure you understand the following:

  • The PNG must be: 640x480 16 colours. If you are using a different console mode, the image will be centered (both horizontally and verically) and the area around it will be filled with the background colour (image's palette colour #0).
  • Some palette entries are used for particular purposes:




Background color


Text background color


Progress bar color


Text foreground color (right)


Progress bar background color


Text foreground color (left)


Failure color

  • The development version of GIMP (CVS or version 2.3.10 or later) has a new plug-in which lets you drag entries in the colormap (palette) to rearrange them. This plug-in is helpful in making these splash images. It is called "Rearrange Colormap" and is available in the image menu at Colors->Map->Rearrange Colormap. You _may_ have to save to a different format other than PNG though and convert back to PNG using a different program as the PNG export plug-in may rearrange the colormap.

After that, the process is simple, just follow these steps:

1. Install BOGL packages needed

sudo apt-get install libbogl-dev 

2. Run these steps to get your splash built:

#convert -colors 16 yourimage.png usplash-artwork.png
cp yourimage.png usplash-artwork.png
pngtobogl usplash-artwork.png > usplash-artwork.c
gcc -Os -g -I/usr/include/bogl -fPIC -c usplash-artwork.c -o usplash-artwork.o
gcc -shared -Wl,-soname,usplash-artwork.so usplash-artwork.o -o yourimage-splash.so 

3. Create a directory for local usplash images (if necessary) and copy your new splash to it:

sudo mkdir -p /usr/local/lib/usplash/
sudo cp yourimage-splash.so /usr/local/lib/usplash/yourimage-splash.so

4. Add your splash to the alternatives system:

sudo update-alternatives --install /usr/lib/usplash/usplash-artwork.so usplash-artwork.so /usr/local/lib/usplash/yourimage-splash.so 55

If this is not the first alternative you have added for usplash-artwork.so, you may also need to select this alternative explicitly. Run:

sudo update-alternatives --config usplash-artwork.so

and select the /usr/local/lib/usplash/yourimage-splash.so file (the file that you have just added to alternatives).

5. Regenerate the initramfs:

sudo dpkg-reconfigure linux-image-$(uname -r)

6. Configure GRUB: A MUST FOR Dapper Drake (6.06)!

Open you GRUB configuration file.

gksudo gedit /boot/grub/menu.lst

To proceed, you'll need to know the framebuffer code for your desired resolution:











  1. Automatic (and update-proof) GRUB Configuration

Find the line

# defoptions=quiet splash

and add your framebuffer resolution code, e.g. (for 1024x768)

# defoptions=quiet splash vga=791

(Don't "uncomment" the line - it only works when it is "commented".)

Save the file, then execute

sudo update-grub

This will now keep even after any future kernel update, unlike the method below. You're all done.

  • B. Manual (kernel-specific) GRUB configuration

NOTE: This is a less recommended approach. Any future kernel updates will not keep your framebuffer resolution setting. Even worse, the setting on your old kernels will likely be lost. The preferred approach is listed above.

Look for a line that corresponds to your kernel, e.g.

kernel          /boot/vmlinuz-2.6.15-23-386 root=/dev/hda1 ro quiet splash

and add the desired framebuffer code at the end of the line, e.g.

kernel          /boot/vmlinuz-2.6.15-23-386 root=/dev/hda1 ro quiet splash vga=791

That's all. Reboot, and enjoy.

If your bootup is now black, try setting vga=788, not vga=785, some video cards may not do 640x480.

Discussion about USplash errors in Dapper moved to USplashCustomizationHowtoDiscussion. If you experience problems with USplash, please go there.

USplashCustomizationHowto (last edited 2009-11-04 16:10:41 by shnatsel)