Operate and Troubleshoot Plymouth from the Command Line

You will finish with a small, safe set of checks for Plymouth: confirm whether its boot daemon is running, find the installed splash-plugin directory, understand why a graphical splash might not appear, and restore the display after a test. 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. Showing, hiding or quitting the splash can affect a live boot or shutdown screen, so use those commands only when you understand 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 does not need 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. The client being installed does not prove that the daemon is running, and a command can fail simply because the machine is no longer in a Plymouth-controlled boot phase.

2. Test whether the daemon is available

Use --ping. It checks the boot daemon without asking it to change the display:

$ 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. A status of 0 means the daemon answered. It does not mean that a graphical theme is active or that KMS is working.

If you need more context, rerun the command with --debug. Treat debug output as diagnostic data rather than as a repair command. Look at the system journal using the tools and service names provided by your distribution; Plymouth's client manpage does not define a universal journal query.

3. Check whether a splash can be selected

Ask for the directory where splash plugins are installed:

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

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

$ 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 requires editing your boot-loader configuration and rebooting. Make that change through your distribution's documented configuration path, and keep a known-good boot entry for recovery.

4. Use display controls only during a controlled test

When a daemon is active and you intentionally 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 may 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 available. If the daemon has already exited, there is no persistent Plymouth setting to undo; the next boot starts a new 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 notifications or synchronisation controls, not general-purpose logging commands. Calling them from an ordinary interactive shell often returns a failure because no boot daemon is listening.

The update subcommand 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.