Check and Control plymouth from the Shell

Your boot splash freezes on a blank screen, and plymouth is the safe way to find out why without touching the boot process itself. This walkthrough uses the installed plymouth client to ping the boot daemon, send progress updates, show a temporary message, and spot the commands that can interrupt a live splash. The examples use Ubuntu's plymouth package version 24.004.60-1ubuntu7.2, and the whole thing takes about 10 minutes. Most of these are ordinary user commands: they just do nothing useful unless the boot daemon is running in the same boot environment.

1. Check the installed interface

Ask the binary for its own help before trusting anything a man page says about it. An installed build can expose more subcommands than an older local manpage describes: on this machine, --help lists reload, which the installed plymouth(1) manpage never documents.

plymouth --help
dpkg-query -W -f='${Package} ${Version}\n' plymouth

Expected version output looks like this:

plymouth 24.004.60-1ubuntu7.2

2. Check whether the daemon is available

--ping is a non-destructive probe. It checks for a running boot daemon and hands back a status code rather than a friendly success message.

if plymouth --ping; then
    echo "plymouthd is running"
else
    echo "plymouthd is not reachable"
fi

A successful probe prints the first message and exits with status 0. A failed probe usually prints nothing and drops into the second branch. A normal desktop shell often has no Plymouth daemon to talk to, so a failure here is not, on its own, a boot problem.

You can also ask for the directory used for splash plugins:

plymouth --get-splash-plugin-path

On the stated installation this prints /usr/lib/x86_64-linux-gnu/plymouth/. It is a reporting option only: it does not install or select a theme.

3. Send a progress update

system-update tells the daemon how far an update has got. Its --progress value is an integer percentage, meant for boot or update orchestration, not for turning a desktop splash into a general-purpose progress bar.

plymouth system-update --progress=42

With no daemon available, this exits unsuccessfully. Called in the correct boot context it sends the update and normally produces no terminal output, so check the status explicitly when you use it in a script:

plymouth system-update --progress=42
status=$?
if [ "$status" -ne 0 ]; then
    printf 'Plymouth update failed, status %s\n' "$status" >&2
fi

Keep the value inside the meaningful percentage range, and do not treat a silent command as proof that a visible splash changed. The daemon and its current mode decide what the user actually sees, not your exit code.

4. Show a short status message

Use display-message with --text when a boot component needs to say something short. Hiding it later needs the exact same text string, so pick it once and reuse it.

plymouth display-message --text="Checking the filesystem"
plymouth hide-message --text="Checking the filesystem"

Both commands are safe to run as probes, but they only do anything visible with an active daemon and a theme that displays messages. If the first command fails, there is no message left to recover. In a service or init script, use a fixed message string rather than generating a new one on every update, so the hide command can still match it later.

5. Show or hide the splash deliberately

show-splash and hide-splash change the display state of the running daemon.

plymouth show-splash
plymouth hide-splash

Neither command starts plymouthd, chooses a theme, or repairs a missing graphical console. If a test hides a splash that another boot component expects to see, put it back with:

plymouth show-splash

6. Treat input and quit commands as privileged operations

• Password and question prompts carry real input. ask-for-password and ask-question can send the user's answer to a command over standard input. The password form takes --prompt, --command, and optionally --number-of-tries. Treat it as security-sensitive: the receiving command, its arguments, its logs, and its process environment all have to be trusted. Never paste a real password into a shell command or hand one to a process as an argument.
• Quit is not a harmless test. quit tells the daemon to exit, which normally removes the boot splash. It can disrupt boot presentation and expose console output at the wrong moment, so do not run it on a production machine just to test the client. If a boot script owns the daemon's lifecycle, let that script decide when to quit. --retain-splash changes whether the splash is explicitly hidden on exit; it does not make quitting harmless.
• Shared state needs one owner. deactivate, reactivate, pause-progress, and unpause-progress all touch shared boot display state, so use them only from the component that owns it. sudo is not a fix for a failed client command: elevated privileges do not conjure up a daemon or a graphical virtual terminal.

7. Use the option names your binary actually supports

The compatibility options such as --show-splash, --hide-splash, --ping, and --quit sit alongside the newer command form. Prefer the command form in new scripts; it makes the action clearer at a glance:

plymouth show-splash
plymouth hide-splash
plymouth quit

The final line is shown only as a reference. It is a service-disrupting action, so keep it out of an unattended test. For a script that has to support one specific installed version, validate the command with plymouth --help at deployment time and fail closed if the option you need is missing.

Done means

• Recorded the version. You noted the installed package version and checked its local help.
• Confirmed daemon reachability. You know whether plymouthd is reachable from the current shell.
• Checked exit status. Your progress or message command checks its exit status rather than assuming success.
• Kept a recovery path. You can restore a test display with plymouth show-splash.
• Avoided casual risk. You did not use quit or password forwarding as a casual diagnostic.