Run and Debug plymouthd from a Recovery Shell

plymouthd is the daemon behind the boot splash, and starting a second copy by accident is how a debugging session turns into a broken console. This guide shows you how to identify the installed interface, pick the right boot or shutdown mode, and run a diagnostic copy without stepping on the one already running. It uses plymouth 24.004.60-1ubuntu7.2, installed here on Ubuntu. Allow about fifteen minutes for inspection, longer if you are debugging an initrd.

plymouthd is normally started from the initrd. It does the actual work behind the Plymouth splash, records the session, and answers control requests from the plymouth client. Starting a second copy on a running desktop or boot session can interfere with that work, so everything here begins with read-only checks.

1. Confirm the binary and version

Run these as an ordinary user. They inspect the installed executable and package; none of them start the daemon:

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

The path can differ on another distribution. What matters is that the command resolves to the package you actually intend to troubleshoot, and that its help output is available.

2. Know where the daemon boundary sits

plymouthd is not the interactive command for changing a splash screen; the separate plymouth command sends requests to it. Reach for plymouthd itself only when the boot or shutdown environment needs the server, or when you need server-side diagnostics.

The options documented in this installed manpage are:

• --no-daemon keeps the process in the foreground instead of daemonising it.
• --debug turns on debugging output, and --debug-file=PATH chooses where it goes.
• --mode=boot or --mode=shutdown selects the session mode.
• --pid-file=PATH writes the daemon's process ID to the named file.
• --tty=PATH selects a TTY instead of the default.
• --attach-to-session redirects console messages from the screen to the log.

Do not guess a default TTY, log path or PID-file path from the option names alone. The manpage makes no promises about those values, and your distribution's initrd integration can supply its own.

3. Select boot or shutdown mode

Boot mode drives the normal startup splash, shutdown mode drives the end-of-session splash. The mode is a property of how the daemon was invoked, not a cosmetic label you can flip safely mid-session.

$ plymouthd --help | grep -- '--mode'
  --mode=<string>                   Mode is one of: boot, shutdown

That output comes from the installed binary. If a boot script or initrd generator already supplies a mode, inspect that generated configuration and the script that launches it rather than starting a competing daemon by hand. A mode mismatch is a plausible reason for a splash that behaves during boot but misbehaves at shutdown.

4. Prepare a foreground diagnostic run

With an unused test TTY and a writable temporary directory, keep the process in the foreground and send diagnostics to a disposable file:

# plymouthd --no-daemon --debug \
    --debug-file=/tmp/plymouthd-debug.log \
    --pid-file=/tmp/plymouthd.pid \
    --mode=boot \
    --tty=/dev/tty1

The command is shown with a root prompt deliberately, since the test environment may need access to the TTY and Plymouth's runtime resources. Exact permissions depend on the initrd and distribution. Stop with Ctrl-C when the foreground test is done: that stops this test process only, it does not repair a service that another supervisor has already started.

In a second shell, check the files you asked for:

# test -s /tmp/plymouthd-debug.log && echo 'debug log has data'
debug log has data
# cat /tmp/plymouthd.pid
1234

The PID shown is an example and will differ. If the log is empty, check first that the path is writable and that the daemon actually reached the point where it emits diagnostics. A PID file existing is not, by itself, proof that the splash is working.

5. Use the installed help to spot version differences

The local manpage documents the core options above, but this package's binary also reports --no-boot-log, --ignore-serial-consoles and --graphical-boot in --help. These are observations specific to plymouth 24.004.60-1ubuntu7.2, not options to assume exist on another host. Check the target machine's own help before copying an initrd argument from this guide.

$ plymouthd --help | tail -3
  --no-boot-log                     Do not write boot log file
  --ignore-serial-consoles          Ignore serial consoles
  --graphical-boot                  Use graphical splashes even if the kernel console is not a VT

Do not add an option just because a different distribution's Plymouth guide mentions it. An initrd generator can reject an unknown argument before the daemon gets anywhere near showing a splash.

6. Diagnose without destroying the evidence

Preserve the original boot log and initrd before you touch anything. Collect read-only facts and the diagnostic file first:

$ command -v plymouthd
$ plymouthd --help > /tmp/plymouthd-help.txt
$ ls -l /tmp/plymouthd-debug.log /tmp/plymouthd.pid
$ sed -n '1,120p' /tmp/plymouthd-debug.log

If the TTY looks wrong, confirm the device exists with ls -l /dev/tty1 and pick a TTY that actually belongs to the test environment. If the daemon exits immediately, check its exit status and the first diagnostic lines before touching permissions or deleting runtime files. Failing to write a debug or PID file is usually a path or permission problem, not proof that the splash plugin is broken.

Once the test is finished, remove only the temporary files you created yourself, and only if they hold no evidence you still need:

# rm -f /tmp/plymouthd-debug.log /tmp/plymouthd.pid /tmp/plymouthd-help.txt