Turn XDG Autostart Entries into Inspectable systemd User Units

You will trace a desktop autostart entry from its .desktop file to the transient systemd user service that runs it. The workflow also gives you a safe way to test the installed generator in a temporary directory. Allow about fifteen minutes. You need a systemd user session and a shell; root is not required for the inspection or the temporary test.

This guide describes systemd 255, installed here as package version 255.4-1ubuntu8.17. Generator details can vary between systemd releases, so treat the output from your own machine as authoritative.

1. Check what is installed

The generator is a user unit generator, not an ordinary command with a useful interactive interface. Confirm the package and executable first:

$ systemd --version
systemd 255 (255.4-1ubuntu8.17)
$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ ls -l /usr/lib/systemd/user-generators/systemd-xdg-autostart-generator
-rwxr-xr-x ... /usr/lib/systemd/user-generators/systemd-xdg-autostart-generator

The exact permission line and package suffix will differ. Do not run the generator with --help: it expects output-directory arguments, so that invocation treats the word as a path and produces misleading file errors.

2. Find the source desktop entry

XDG autostart uses .desktop files. A per-user entry normally lives under ~/.config/autostart/; system-wide entries normally live under /etc/xdg/autostart/. The XDG specification gives the user directory precedence when the same filename exists in both places.

Search without changing anything:

$ find "$HOME/.config/autostart" /etc/xdg/autostart \
    -maxdepth 1 -type f -name '*.desktop' -print 2>/dev/null
/home/USER/.config/autostart/example.desktop
/etc/xdg/autostart/example.desktop

Replace USER only in the example output, not in a command you paste. If one filename appears in both directories, inspect the user copy first. A user-level Hidden=true entry can disable a system-wide entry with the same name.

Checkpoint: inspect the relevant keys before blaming systemd:

$ sed -n '1,120p' "$HOME/.config/autostart/example.desktop"
[Desktop Entry]
Type=Application
Name=Example notifier
Exec=/usr/bin/example-notifier
OnlyShowIn=GNOME;

Pay particular attention to Hidden, X-systemd-skip, TryExec, OnlyShowIn, NotShowIn and desktop-environment-specific condition keys. Some of these prevent a unit being generated; others become an ExecCondition that can stop the service from starting.

3. Reload the user manager

Generators run automatically when systemd loads or reloads its configuration. After changing a user autostart file, reload the user manager as the ordinary account:

$ systemctl --user daemon-reload

This removes old generated output, runs the user generators again and reloads the unit tree. It does not require sudo. If the command says there is no user bus, perform the check from inside the logged-in graphical session that owns the autostart entry.

Do not edit files under $XDG_RUNTIME_DIR/systemd/generator*. They are generated state and will be replaced on the next reload. Edit the source .desktop file instead.

4. Inspect the generated service

The generator names an entry from its desktop filename. For example.desktop, ask the user manager for the generated unit:

$ systemctl --user cat [email protected]
# /run/user/1000/systemd/generator.late/[email protected]
# Automatically generated by systemd-xdg-autostart-generator

[Unit]
Documentation=man:systemd-xdg-autostart-generator(8)
SourcePath=/home/USER/.config/autostart/example.desktop
PartOf=graphical-session.target

[Service]
Type=exec
ExecStart=:/usr/bin/example-notifier
Restart=no
Slice=app.slice

The numeric user ID, source path, description and service details depend on the entry. The generated unit is normally attached to graphical-session.target, and the desktop environment can start it through xdg-desktop-autostart.target. A unit may also contain an ExecCondition for desktop visibility or a vendor-specific condition.

If systemctl --user cat reports that the unit does not exist, check the filename-derived unit name, reload again, and then inspect the source keys. Hidden=true, X-systemd-skip=true, an unusable TryExec, and an ignored desktop phase are common reasons for no generated service.

5. Test the generator without changing your session

For a reproducible diagnosis, run the generator with three temporary output directories. The service manager normally supplies these arguments; they are not options you configure in the desktop file. This test uses a harmless command and a temporary XDG configuration directory.

$ testdir=$(mktemp -d /tmp/xdg-autostart-test.XXXXXX)
$ mkdir -p "$testdir/config/autostart" "$testdir/normal" \
    "$testdir/early" "$testdir/late"
$ cp "$HOME/.config/autostart/example.desktop" \
    "$testdir/config/autostart/example.desktop"
$ XDG_CONFIG_HOME="$testdir/config" XDG_CONFIG_DIRS=/nonexistent \
    /usr/lib/systemd/user-generators/systemd-xdg-autostart-generator \
    "$testdir/normal" "$testdir/early" "$testdir/late"
$ find "$testdir" -path '*.service' -type f -print
/tmp/xdg-autostart-test.ABC123/late/[email protected]

Open the resulting service to see exactly what systemd would load:

$ sed -n '1,160p' "$testdir/late/[email protected]"
# generated unit contents appear here

The suffix is escaped when needed, so filenames containing unusual characters may not map to the name you first guess. Use the path printed by find as the source of truth. This direct test does not start the application.

6. Fix the source and recover cleanly

Change the .desktop file only after deciding whether the application should start in this desktop environment. For a user override, keep the original system file untouched and create or edit the same filename under ~/.config/autostart/. To undo that override, remove the user copy and reload the user manager:

$ rm -- "$HOME/.config/autostart/example.desktop"
$ systemctl --user daemon-reload

The removal is irreversible unless you have a backup, so copy the file first if it contains useful settings. Do not delete a system-wide file as a shortcut; that requires elevated privileges and affects other users. If the service starts an unwanted program, stop the generated unit for the current session while you investigate:

$ systemctl --user stop [email protected]

Stopping it does not repair the source entry. The next graphical-session start can activate it again until the .desktop file is corrected or hidden.