Diagnose Plymouth Without Breaking the Splash

A blank screen during boot tells you nothing, and prodding it with the wrong plymouth command can make things worse. This guide gives you a safe set of checks: confirm whether the boot daemon is running, find the installed splash-plugin directory, work out why a graphical splash might not appear, and put the display back the way you found it. The examples target the installed plymouth package version 24.004.60-1ubuntu7.2.

Allow about ten minutes. You need a shell on a Linux system using Plymouth. Most checks are ordinary commands, but showing, hiding or quitting the splash can affect a live boot or shutdown screen, so only run those once you know what is currently running. Do not test password or question prompts with real credentials.

1. Check the installed client

Start with the command's own help. This is read-only and needs no elevated privileges:

$ command -v plymouth
/usr/bin/plymouth
$ dpkg-query -W -f='${Package} ${Version}\n' plymouth
plymouth 24.004.60-1ubuntu7.2
$ plymouth --help

The client talks to plymouthd, the boot daemon. Having the client installed proves nothing about whether that daemon is running, and a command can fail simply because the machine has already left the Plymouth-controlled boot phase.

2. Test whether the daemon is available

Use --ping. It checks the boot daemon without asking it to change anything on screen:

$ plymouth --ping
$ printf 'exit status: %s\n' "$?"
exit status: 1

On this machine the daemon is not running, so status 1 is expected outside a boot or shutdown transition. Status 0 means the daemon answered, nothing more: it does not mean a graphical theme is active or that KMS is working.

Need more context? Rerun with --debug, and treat that output as diagnostic data rather than a repair command. Check the system journal with the tools and service names your distribution provides; Plymouth's own client manpage does not define a universal journal query.

3. Check whether a splash can be selected

Ask for the directory where splash plugins live:

$ plymouth --get-splash-plugin-path
/usr/lib/x86_64-linux-gnu/plymouth/

That is an installation path, not the currently selected theme. Theme selection is handled by the separate plymouth-set-default-theme tool, which sits outside this guide. Do not delete files from the returned directory: a plugin is code that Plymouth loads, and removing one can break boot graphics outright.

$ tr ' ' '\n' < /proc/cmdline | grep -E '^(splash|rhgb)$' || echo 'no Plymouth splash flag found'
no Plymouth splash flag found

The exact output is host-specific. Adding a kernel argument changes boot behaviour and normally means editing your boot-loader configuration and rebooting. Make that change through your distribution's own documented path, and keep a known-good boot entry around for recovery.

4. Use display controls only during a controlled test

When a daemon is active and you deliberately need to restore its display, the paired operation is:

# plymouth --show-splash
# printf 'exit status: %s\n' "$?"
exit status: 0

# plymouth --hide-splash
# printf 'exit status: %s\n' "$?"
exit status: 0

The leading # marks a root shell. Your output may differ, and these commands can return a non-zero status when no daemon is present. If a test leaves the screen hidden, run plymouth --show-splash while the daemon is still reachable. Once the daemon has exited there is no persistent Plymouth setting left to undo: the next boot simply starts a fresh transition.

5. Understand progress and error notifications

Boot infrastructure can report status with --update=<string>, report a boot error with --details, and wait for the daemon with --wait. These are notification and synchronisation controls, not general-purpose logging commands, and calling them from an ordinary interactive shell usually fails because no boot daemon is listening.

update is the explicit command form for a status string:

# plymouth update --status='boot-check'
# printf 'exit status: %s\n' "$?"
exit status: 1

Use a short, non-sensitive status value supplied by the boot workflow. Never put passwords, tokens or arbitrary user input into a displayed message or a command passed to an ask operation.