# Plymouth

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Related articles

- Silent boot

Plymouth is a project from Fedora and now listed among the freedesktop.org's official resources providing a flicker-free graphical boot process. It relies on kernel mode setting (KMS) to set the native resolution of the display as early as possible, then provides an eye-candy splash screen leading all the way up to the login manager.

## Preparation

Plymouth primarily uses KMS (Kernel Mode Setting) to display graphics. In EFI/UEFI systems, plymouth can utilize the EFI framebuffer. If you cannot use KMS, e.g. because you are using a proprietary driver, or if you do not want to use the EFI framebuffer, consider using Uvesafb as it works with widescreen resolutions.

If you have neither KMS nor a framebuffer, Plymouth will fall back to text-mode.

## Installation

Plymouth is available from the AUR: the stable package is plymouthAUR and the development version is plymouth-gitAUR. Due to the fact that upstream plymouth release only happen on a spotty and highly unregular schedule, it is generally recommended to use plymouth-gitAUR, because it is actually less likely to cause problems for most users than the stable package.

### The plymouth hook

Add `plymouth` to the `HOOKS` array in mkinitcpio.conf. It must be added after `base` and `udev` for it to work:

    /etc/mkinitcpio.conf

    HOOKS=(base udev plymouth ...)

Warning:

- If you use hard drive encryption with the `encrypt` hook, you must replace the `encrypt` hook with `plymouth-encrypt` and add it after the `plymouth` hook in order to get to the TTY password prompts.
- Using `PARTUUID` or `PARTLABEL` in `cryptdevice=` parameter does not work with `plymouth-encrypt` hook.
- For a ZFS encrypted root, you must install plymouth-zfsAUR and replace the `zfs` hook with `plymouth-zfs`

After adding the `plymouth-encrypt` hook, if input goes to the background in plaintext instead of into the password prompt you need to add your (kernel) graphics driver to your initramfs. For example, if using intel:

    /etc/mkinitcpio.conf

    MODULES=(i915 ...)

This might also be a step needed for some themes to work.

### Alternative plymouth hook (systemd)

If your mkinitcpio.conf includes the `systemd` hook, then replace `plymouth` with `sd-plymouth`. Additionally, if using hard drive encryption, use `sd-encrypt` instead of `encrypt` or `plymouth-encrypt`:

    /etc/mkinitcpio.conf

    HOOKS=(base systemd sd-plymouth ... sd-encrypt ...)

### The kernel command line

Append `quiet splash vt.global_cursor_default=0` to the kernel parameters. See Silent boot for other parameters to limit the output to the console.

## Configuration

### Smooth transition

If using GDM, install gdm-plymouthAUR which supports smooth transition out of the box (no other steps are required as it cleanly replaces gdm).

Optimus-manager users on GDM can install gdm-plymouth-primeAUR, which is a fork of gdm-plymouthAUR with the required patches to support Prime switching.

Users of other display managers (SDDM, LightDM or LXDM) will have to:

1. Disable your display manager unit, e.g. `lxdm.service`.
2. Enable the respective DM-plymouth unit provided, e.g. `lxdm-plymouth.service`.

### Show delay

Plymouth has a configuration option to delay the splash screen:

    /etc/plymouth/plymouthd.conf

    [Daemon]
    Theme=spinner
    ShowDelay=5

On systems that boot quickly, you may only see a flicker of your splash theme before your DM or login prompt is ready. You can set `ShowDelay` to an interval (in seconds) longer than your boot time to prevent this flicker and only show a blank screen. The default is 5 seconds, but you may wish to change this to a lower value to see your splash earlier during boot.

### Change background image

Certain themes (such as spinner) can have their background image changed. On spinner, by default it is a grey noise pattern. To change it, replace `/usr/share/plymouth/themes/theme/background-tile.png` with your desired image. You may want to copy and create a new theme when doing this, to prevent it from being overridden by updates to Plymouth. Do not forget to regenerate the theme once changed, see the next section for how.

### Changing the theme

Plymouth comes with a selection of themes:

1. Fade-in: "Simple theme that fades in and out with shimmering stars"
2. Glow: "Corporate theme with pie chart boot progress followed by a glowing emerging logo"
3. Script: "Script example plugin" (Despite the description seems to be a quite nice Arch logo theme)
4. Solar: "Space theme with violent flaring blue star"
5. Spinner: "Simple theme with a loading spinner"
6. Spinfinity: "Simple theme that shows a rotating infinity sign in the center of the screen"
7. BGRT: A variation of Spinner that keeps the OEM logo if available (BGRT stands for Boot Graphics Resource Table)
8. (Text: "Text mode theme with tricolor progress bar")
9. (Details: "Verbose fallback theme")

In addition you can install other themes from AUR, just have a look at the "Required by"-Array on plymouthAUR.

All currently installed themes can be listed by using this command:

    $ plymouth-set-default-theme -l

or:

    $ ls /usr/share/plymouth/themes

    details  glow    solar       spinner  tribar
    fade-in  script  spinfinity  text

By default, the spinner theme is selected. The theme can be changed by editing `/etc/plymouth/plymouthd.conf`, for example:

    /etc/plymouth/plymouthd.conf

    [Daemon]
    Theme=spinner
    ShowDelay=5

Themes can be previewed without rebuilding, press `Ctrl+Alt+F6` to switch to a text terminal, log in as root and type:

    # plymouthd
    # plymouth --show-splash

To quit the preview, press `Ctrl+Alt+F6` again and type:

    # plymouth --quit

Every time a theme is changed, the `initrd` must be rebuilt. The `-R` option ensures that it is rebuilt (otherwise manually run `mkinitcpio -P`):

    # plymouth-set-default-theme -R theme

### Hidpi

Edit `plymouthd.conf` as

    /etc/plymouth/plymouthd.conf

    DeviceScale=<an-integer-scaling-factor>

and rebuild the initrd.

## Tips and tricks

#### Show kernel messages

During boot you can switch to kernel messages by pressing the `Home` or `Esc` keys.

### Adding Arch Logo to spinner and BGRT themes

To add the Arch Logo to the spinner and BGRT themes copy the Arch logo to the spinner theme directory with the name `watermark.png`:

    # cp /usr/share/plymouth/arch-logo.png /usr/share/plymouth/themes/spinner/watermark.png

To center the logo (if not already centered), add the following lines to the theme's configuration file (file name ending with `.plymouth`, e.g. `spinner.plymouth`):

    WatermarkHorizontalAlignment=.5
    WatermarkVerticalAlignment=.5

### Replacing the Arch Logo and creating custom themes

The following themes use the Arch Linux logo supplied by Plymouth in `/usr/share/plymouth/arch-logo.png`: fade-in, script, solar, spinfinity. If you want to use another logo, you can take one of them or one of the plymouth themes in AUR, edit the file `*.plymouth` (and maybe `*.script`, too) and replace this image with one of your choice. You should create a package from your newly created theme, because changes in `/usr/share/plymouth` may not be persistent across package upgrades.

After installing and selecting your theme, you should rebuild the initrd image to use the new splash.

### Disable vendor logo

Add `fbcon=nodefer` to kernel parameters.

## Troubleshooting

### "Unit configured to use KillMode=none" error message in logs

As of plymouth v0.9.5-6 and systemd 247.2-1, the following error message appears with high frequency in the system log:

     systemd[1]: /etc/systemd/system/plymouth-start.service:15: Unit configured to use KillMode=none. This is unsafe, as it disables systemd's process lifecycle management for the service. Please update your service to use a safer KillMode=, such as 'mixed' or 'control-group'. Support for KillMode=none is deprecated and will eventually be removed.

See the upstream issue for more details.

This issue has now been fixed by upstream. However, because a new versioned release with the fix has yet to be released, the plymouthAUR package also still has this issue. plymouth-gitAUR already incorporates the fix (as of late February, 2021).

## See also

- Original Spec
- Related forum thread

Category:

- Bootsplash