XDG-XSESSION(1)

🦋 XDG-XSESSION(1) 🦋

User Commands — yep, this is the XDG-XSESSION(1) manual, bestie. It's giving “tiny launcher, lots of lore.” 💅

🌸 NAME 🌸

xdg-xsession — an XDG compliant XSession startup notification launcher ✨

💖 SYNOPSIS 💖

xdg-xsession [OPTIONS] [APPID|COMMAND]

🎀 DESCRIPTION 🎀

Okay so xdg-xsession is a script that simply executes xdg-launch(1) with the appropriate arguments (--xsession). That's it. That's the whole main-character move. 🫶

For more info, see "COMMAND OPTIONS" in xdg-launch(1).

🦋 FILE FORMAT 🦋

Bestie, there are two formats for the .desktop file of type XSession:

1. An entry for a window manager that may or may not be capable of being launched under multiple session managers.
2. An entry for a session manager that may or may not include optional window managers.

Detecting between the two can be performed fairly reliably on the basis of examining the XSession desktop entry keys and values. iykyk 🔍

🌼 GROUPS 🌼

The group is literally:

[Desktop Entry]

🎀 [Desktop Entry] 🎀

⭐ Standard Keys ⭐

The Desktop Entry group may contain the following standard keys:

• Type — this required key specifies the type of the desktop entry. The standard type for application desktop entry files is Application. The “Desktop Entry Specification” dictates that unrecognized types are to be ignored.

The non-standard type for X session desktop entry files is XSession. This key is normally set to Application when the desktop entry file may also reside in applications directories.

The non-standard type for auto-start desktop entry files is Autostart. This key is normally set to Application when the desktop entry file may also reside in applications directories.

KDE specifies additional non-standard types that are typically ignored by all but KDE applications and utilities.

• Version — this optional key specifies the version of the “Desktop Entry Specification” to which the remainder of the file conforms. The current version is 1.1. The current version is backward compatible with version 1.0. There are backward incompatibilities between pre-1.0 files and file of version 1.0 and later. This key is, therefore, only really necessary when identifying a pre-1.0 (e.g. 0.9) file version.

Unless a file is a pre-1.0 version, this key is normally omitted.

As there are no standard versions for XSession or Autostart files, this key is normally omitted in those files.

• Name[] — this required key specifies the name of the entry. 🎀
• GenericName[] — the optional generic name of the entry (e.g. Window Manager).
• NoDisplay — this optional key, when set to true, indicates that the entry should not be displayed in the menus. The key is normally only included to set it to true. This is often for application that perform some other function (such as an XSession or Autostart entry, one that just sets its MimeType, etc.).

For X sessions and auto-start entries, this key is ignored by the x session and auto-start launcher, as it is primarily for use in applications sub-directories only.

• Comment[] — this optional key provides a longer description of the application: still normally only consuming one line of text. 📝
• Icon — this optional key specifies an icon name for the desktop entry. The icon name should not have an extension, and should not contain a path; however, many applications recognize both extension and path. Where only an extension is specified and not a path, the application typically restricts the selection of icon to one with the same extension as that specified. Where a path is specified, it is normally only used to specify an icon that resides outside the normal search paths for icons. 🌸
• Hidden — this optional key is normally only included when specified as true. It is used to occlude entries in search path sub-directories with a lower priority than the one in which the .desktop file resides.
• OnlyShowIn — specifies an exclusive list of desktops in which the application is shown in the menus.

This entry is meaningless for X sessions, as the current XDG desktop has not yet been set. This entry is also meaningless for many auto-start entries, especially those that start before the current desktop is set.

• NotShowIn — specifies an exclusion list of desktop for which the application is not shown in the menus.

This entry is meaningless for X sessions, as the current XDG desktop has not yet been set. This entry is also meaningless for many auto-start entries, especially those that start before the current desktop is set.

• DBusActivatable
• TryExec — this optional key typically contains the absolute path and file name of a binary executable that must exist for the desktop entry to be considered valid. It is often specified when the Exec key does not contain the primary binary executable in the first word of the command. It may also be specified without a path, in which case the $PATH environment variable is used to search for the executable as would which(1). This key is not shell word expanded by the application.
• Exec
• Path
• Terminal — specifies that the application is to be started as the executed command of a terminal (e.g. xterm -e).
• Actions
• MimeType
• Categories — this optional key specifies a list of categories for the entry.

XSession entries have this key set to WindowManager;System;Applications;.

Autostart entries can set this key to give hints to the session manager as to when the auto-start entry should be launched. These hints are:

• Panel
• TrayIcon
• SystemTray
• DesktopPager
• Dock
• DockApp
• WindowManager
• CompositeManager

• Implements
• Keywords
• StartupNotify — provides a tri-state boolean value and specifies whether the desktop entry supports startup notification completion. This key should be specified as false when it is known that the application does not perform startup notification and does not map any window (regardless of the setting of the StartupWMClass key); true, when it is known that it will perform startup notification completion when invoked with a DESKTOP_STARTUP_ID environment variable set; and, not present when it is unknown whether the desktop entry supports startup notification or not.

When used in an X session file, this property refers to the window manager or session launched. A session manager interpreting this key when set to false in the X session file, or when not specified and the StartupWMClass and X-GNOME-WMName class are not set, should the session manager or auto-start dispatcher send a new: message when launching the window manager, it should not await a remove: message and should send one itself on appearance of a window manager. Should it send a new: message in such cases, the new: message should contain the SILENT=1 parameter.

When this key is not present and the StartupWMClass or X-GNOME-WMName keys are present, the window manager launcher should await the appearance of an EWMH check window with the appropriate class or name before sending the remove: message. Any sent new: message should not contain the SILENT parameter. 😭

• StartupWMClass — if specified, it is known that the application will map at least one window with the given string as its WM class or WM name hint. xdg-launch(1), when Terminal is set to true, will use this value to have the terminal populate the res_class portion of the WM_CLASS property on the terminal, and this value in all lower-case to populate the res_name portion of the WM_CLASS property on the terminal. See XGetClassHint(3). 💅

💀 Deprecated Keys 💀

The Desktop Entry group may contain the following deprecated standard keys:

• Encoding — this key is deprecated. Its only currently valid value is UTF-8. This key should be ignored by current applications.
• MiniIcon — was used with the %m expansion for Exec strings. Used to expand to --miniicon [MiniIcon], where [MiniIcon] is the value of the MinIcon key.
• TerminalOptions — was used to supply additional terminal options when the Terminal key was set to true. Not used in XSession or Autostart entries.
• Protocols
• Extensions
• Extensions — yes, it's listed twice in the original. Not me. The manual said it. 💀
• BinaryPattern
• MapNotify
• SwallowTitle — a locale string that specified the title of the window if it is swallowed onto the panel.
• SwallowExec — a string that specified the program to execute if the swallowed application was clicked.
• SortOrder — was used to specify sorting order for menus: other mechanisms are used currently.
• FilePattern

🌈 Non-Standard Keys 🌈

The Desktop Entry group may contain the following non-standard, but widely accepted, keys:

• DesktopNames — this optional key is only used in XSession files. It specifies the contents of the $XDG_CURRENT_DESKTOP environment variables, to be set when the session is launched.

Although this key is non-standard, the “Desktop Entry Specification” gives it a glancing reference. It can also be seen in many XSession entry files in the wild. 🦋

• GenericComment[]
• MultipleArgs
• X-MultipleArgs
• Patterns
• SingleInstance
• AsRoot — an optional boolean value that, when true, specifies that the Exec key is to be executed as root (e.g. with sudo(1), or another root privileges command).
• AutostartPhase — the same as X-GNOME-Autostart-Phase, below under “GNOME Extensions”.
• AutostartCondition — a variation of the X-KDE-Autostart-condition key. Provides a complex mechanism for specifying the conditions that must prevail before an auto-start entry is considered for launching. Only applicable to auto-start entries.
• X-DBUS-ServiceName
• X-DBUS-ServiceType
• X-DBUS-StartupType
• X-DCOP-ServiceType
• X-DCOP-StartupType
• X-Desktop-File-Install-Version
• X-DocPath — another name for the widely used DocPath key.

✨ GNOME Extensions ✨

The Desktop Entry group can also carry these "GNOME" extension keys, bestie:

• X-GNOME-AutoRestart — this optional extension key is only included when set to true. It means the application should be restarted if it exits with a non-zero exit status or terminates on a signal. Naturally, the session launching this application must not restart it too rapidly. Applications with X11R6 Session Management could achieve this functionality instead, but it’s often used as an indication to light-weight window managers that a startup application needs to be restarted in this fashion, so it’s a reasonable extension. It mostly applies to X sessions and auto-start entries.
• X-GNOME-Autostart-Notify — this optional extension key is only included when set to true. It means the application will use the DESKTOP_STARTUP_ID environment variable as the session client identifier to register with an X11R6 Session Manager, so the session manager may coordinate auto-start activities. It mostly applies to auto-start entries, and potentially window manager X session entries.
• X-GNOME-Autostart-Phase — this optional key is mostly applicable to auto-start entries and some X session entries. It’s not normally used with X session files unless the X session file specifies only a window manager, in which case the auto-start phase must be set to WindowManager. It’s also not normally used with application files unless they also specify an auto-start entry.

When this optional key is present, it specifies the auto-start phase, which may be one of:

• PreDisplayServer — the first phase of normal startup (startup controlled by .desktop files rather than session manager code). It covers the possible installation of files in $HOME by some initial setup programs and must be done before other components use those files. Not normally used in XDG auto-start. Auto-start applications with this phase set likely also have StartupNotify set to false and StartupWMClass unspecified (because they can’t map windows).
• Initialization — covers low-level stuff like settings helpers that need to be running very early (before any windows are displayed). Some examples would be merging .Xresources files with xrdb(1), setting up .Xmodmap files with xmodmap(1), and executing the shell scripts in /etc/X11/xinit/xinitrd.d/ and $HOME/.xinitrc.d.

More examples: setting up canberra GTK modules, importing the $DISPLAY and $XAUTHORITY environment variables into systemd(8) and also the DBUS activation environment. .desktop files are seldom used instead of scripts for these functions. One exception is the pusle audio X11 integration.

• WindowManager — includes window managers and compositing managers, plus anything else that has to be running before any windows are mapped. xdg-launch(1) also interprets this as the phase necessary to set up docks, slits or harbours for dock apps.
• Desktop — includes anything that draws directly on the desktop (e.g. backgrounder). xdg-launch(1) also interprets this as the phase necessary to set up desktop layouts for desktop pagers.
• Panel — includes anything that permanently takes up screen real estate (via EWMH struts). This is the first phase where things actually appear on the screen. xdg-launch(1) also interprets this as the phase necessary to set up system trays for status icons.
• Application — sometimes called Applications (with the "s" on the end). This is everything else.

• X-GNOME-Autostart-Delay — this optional key is normally only specified when set to a non-zero number of seconds.
• X-GNOME-Bugzilla-Bugzilla, X-GNOME-Bugzilla-Component, X-GNOME-Bugzilla-Product, X-GNOME-Bugzilla-Version, X-GNOME-Bugzilla-OtherBinaries, X-GNOME-Bugzilla-ExtraInfoScript — these keys are ignored by most tools other than "GNOME" tools.
• X-GNOME-WMName — for XSession entries, specifies the name that will be placed on the window manager check window. Note that this may also now be specified with the StartupWMClass key for the window manager.
• X-GNOME-WMSettingsModule — for "GNOME", specifies the window manager settings module to be used by gconf(1). Not useful for other desktops.
• X-GnomeWMSettingsLibrary — for "GNOME", specifies the window manager settings library to be used by gconf(1). Not useful for other desktops.
• X-GNOME-FullName[] — an optional locale string that can be used to specify a longer name for the application.
• X-GNOME-Keywords — old name for the now standard Keywords key.
• X-GNOME-Provides — specifies the capability that the application, auto-start entry or X session provides. Typical values (that may be combined into a semi-colon separated list) are:
  • filemanager
  • login-sound
  • panel
  • screen-keyboard
  • screen-magnifier
  • screen-reader
  • windowmanager

These values may be combined into a list: for example, it is common to see panel;windowmanager; as a value. By far the most common use of this key is to identify in an XSession entry that the entry provides a window manager.

• X-GNOME-DocPath — another name for the widely used DocPath key.
• X-GNOME-Autostart-enabled — the Hidden key is not completely satisfactory for use in enabling or disabling auto-start entries. Therefore, this optional extension key may be used to enable or disable an auto-start entry that is not hidden. Both xdg-launch(1) and xde-session(1) respect this key. When absent on an auto-start entry that is not hidden, the default value of this key is true, instead of false (as is the case for most keys).

xdg-launch(1) handles this key when performing session startup by setting the Hidden key to the inverse of this boolean value when it is present and the launch type is Autostart.

• X-GNOME-Autostart-startup-id, X-GNOME-Autostart-discard-exec — these two extension keys are used by gnome-session(1) to save session state for auto-start entries with X-GNOME-Autostart-Notify set to true. They should never appear in XDG directories.

🦋 KDE Extensions 🦋

The Desktop Entry group may contain the following "KDE" extension keys:

• DocPath, X-KDE-DocPath — another name for the widely used DocPath key.
• InitialPreference, X-KDE-InitialPreference
• Keywords, X-KDE-Keywords — old name for the now standard Keywords key.
• ServiceTypes, X-KDE-ServiceTypes
• X-KDE-StartupNotify — this key was used before the StartupNotify key was standardized. It has similar semantics to the standard StartupNotify key.
• X-KDE-autostart-condition
• X-KDE-autostart-after — this optional key is used to further order auto-start entries that start in the "KDE" auto-start phase 2 (Applications). All auto-start applications in "KDE" phase 2 start after the window manager. Typical values seen in the wild are:
  • panel — auto-start the entry after the panel has already started up. This is roughly equivalent to the "GNOME" auto-start phase just after Panel.
  • kdesktop — auto-start the entry after the desktop has already started up. This is roughly equivalent to the "GNOME" auto-start phase just after Desktop.
• X-KDE-autostart-phase — when present, specifies the auto-start phase for an auto-start entry. This is an integer value that can have one of the following values:
  • 0 — roughly corresponds to the PreDisplayServer "GNOME" auto-start phase.
  • 1 — roughly corresponds to the Initialization "GNOME" auto-start phase.
  • 2 — roughly corresponds to the Applications "GNOME" auto-start phase.

This key only applies to auto-start entries. The default value if not present is the Applications phase (2).

• X-KDE-AuthorizeAction
• X-KDE-BrowserView-Args
• X-KDE-ExtraNativeMimeTypes
• X-KDE-FactoryName
• X-KDE-HasReadOnlyMode
• X-KDE-HasTempFileOption
• X-KDE-Library
• X-KDE-ModuleType
• X-KDE-NativeMimeType
• X-KDE-Protocols
• X-KDE-RootOnly
• X-KDE-StartupNotify — this key was used before the StartupNotify key was standardized. It has similar semantics to the standard StartupNotify key.
• X-KDE-SubstituteUID
• X-KDE-UniqueApplet
• X-KDE-Username
• X-KDE-WindowManagerId
• X-KDE-WindowManagerConfigure
• X-KDE-WindowManagerRestartArgument

🎀 MATE Extensions 🎀

The Desktop Entry group may contain the following "MATE" extension keys, which correspond to the equivalent "GNOME" extension keys:

• X-MATE-AutoRestart — the same as the X-GNOME-AutoRestart key, except for "MATE". See X-GNOME-AutoRestart, above.
• X-MATE-Autostart-Notify — the same as the X-GNOME-Autostart-Notify key, except for "MATE". See X-GNOME-Autostart-Notify, above.
• X-MATE-Autostart-Phase — the same as the X-GNOME-Autostart-Phase key, except for "MATE". See X-GNOME-Autostart-Phase, above.
• X-MATE-Bugzilla-Bugzilla, X-MATE-Bugzilla-Component, X-MATE-Bugzilla-Product, X-MATE-Bugzilla-Version — these keys are ignored by most tools other than "MATE" tools.
• X-MATE-Provides — the same as the X-GNOME-Provides key, except for "MATE". The only values I have seen for "MATE" are:
• panel
  • windowmanager

(peep X-GNOME-Provides, above — same energy 💫)

• X-MATE-WMName — literally the exact same as the X-GNOME-WMName key, just for "MATE" instead. See X-GNOME-WMName, above.
• X-MATE-WMSettingsModule — the same as the X-GNOME-WMSettingsModule key, except it's for "MATE". See X-GNOME-WMSettingsModule, above.
• X-MateWMSettingsLibrary — the same as the X-GnomeWMSettingsLibrary key, except for "MATE". See X-GnomeWMSettingsLibrary, above.

bestie notice the capitalization on that last one — X-MateWMSettingsLibrary is not the same casing pattern as the others, and that's canon, don't @ me, copy it exactly as written 💅

XFCE Extensions 🦋

so the Desktop Entry group can also carry these "XFCE" extension keys:

• X-XFCE-Binaries
• X-XFCE-Category
• X-XFCE-Commands
• X-XFCE-CommandsWithParameter
• X-XFCE-MimeType

SuSE Extensions 🌸

the Desktop Entry group may contain the following "SuSE" extension keys:

• X-SuSE-YaST-RootOnly
• X-SuSE-translate

LightDM Extensions ✨

and the Desktop Entry group may contain this "LightDM" extension key:

• X-LightDM-DesktopName

---

[Desktop Action ACTION] 🎀

okay important vibe check: the Desktop Action group is not used in Autostart entries. not it. 🙅‍♀️

The Desktop Action group may contain the following standard keys:

and that's genuinely where the page stops on that one — no list follows, so I'm not gonna invent one for you, queen 🙈

[Window Manager] 👑

The Window Manager group is a non-standard group, but it's one that a number of session managers actually support. It may contain the following keys:

• SessionManaged
• StartupNotification
• ConfigExec

---

BUGS 🐛

xdg-xsession has no known bugs. iconic, honestly. but if you do find something, please report bugs to the source code repository at <https://github.com/bbidulock/xdg-launch/issues>.

SEE ALSO 👀

xdg-launch(1). that's the whole list, bestie — go read it next, iykyk 💖

AUTHOR 💜

Brian Bidulock <mailto:bidulock@openss7.org>

---

and that's the whole page, bestie!! 🫶 this was xdg-launch version 1.12, dated 2022-01-28 — screenshot it, cite it, love it, periodt. 💅✨