gnome-session — Start the GNOME desktop environment
gnome-session
[OPTION...]
The gnome-session program starts up the GNOME desktop environment. This command is typically executed by your login manager (either GDM, SDDM, lightdm, or other). It will load either your saved session, or it will provide a default session for the user as defined by the system administrator (or the default GNOME installation on your system). Note that gnome-session is a wrapper script for gnome-session-binary, which does the bulk of the work.
The default session is defined in gnome.session
, a
.desktop-like file that is looked for in
$XDG_CONFIG_HOME/gnome-session/sessions
,
$XDG_CONFIG_DIRS/gnome-session/sessions
and
$XDG_DATA_DIRS/gnome-session/sessions
.
--autostart
=DIR
The directory DIR
to be searched for autostart
.desktop files. This option can be used multiple times. When this option
is present, then default autostart directories will not be searched.
--session
=SESSION
Use the applications defined in SESSION.session
.
If not specified, gnome.session
will be used.
--failsafe
Run in fail-safe mode. User-specified applications will not be started.
--debug
Enable debugging code.
--whale
Show the fail whale in a dialog for debugging it.
Sessions are defined in .session
files, that are
using a .desktop-like format, with the following keys in the
GNOME Session
group:
Name
Name of the session. This can be localized.
RequiredComponents
List of component identifiers (desktop files) that are required by the session. The required components will always run in the session.
Here is an example of a session definition:
[GNOME Session] Name=GNOME RequiredComponents=gnome-shell;gnome-settings-daemon;
In systemd managed sessions, the RequiredComponents may be provided by systemd units instead. See the systemd section for more information on how this works.
The .session
files are looked for in
$XDG_CONFIG_HOME/gnome-session/sessions
,
$XDG_CONFIG_DIRS/gnome-session/sessions
and
$XDG_DATA_DIRS/gnome-session/sessions
.
gnome-session will much of the session management over
to systemd, if systemd is available. In this case, startup components that
have X-GNOME-HiddenUnderSystemd=true
set in their
.desktop
file will be ignored by gnome-session.
It instead relies on the fact that these components are managed by systemd.
systemd provides the two special targets for desktop
integration: graphical-session.target
and
graphical-session-pre.target
. These work across desktop
environments, and should be used if possible. gnome-session
provides the following additional GNOME-specific targets:
gnome-session.target
Generic unit that will be active throughout the session.
Similar to graphical-session.target
.
gnome-session-pre.target
Used for tasks that need to be done before session startup.
Similar to graphical-session-pre.target
.
gnome-session-x11@SESSION.target
,
gnome-session-wayland@SESSION.target
Main unit started for X11/wayland based session.
SESSION
is set according to the session that is
passed in via --session
.
gnome-session-x11.target
,
gnome-session-wayland.target
Convenience units without the session embedded into the target.
gnome-session@SESSION.target
Convenience unit with just the SESSION
information embedded.
gnome-session-x11-services.target
Special unit started when X11 services are needed.
Programs will need to use the special GNOME_SETUP_DISPLAY
environment variable instead of DISPLAY
.
Note that care must be taken to set appropriate After=
rules.
It is also strongly recommended to always do this in combination with BindsTo=
or PartOf=
on one of the core targets (e.g. graphical-session.target
).
Units are required to set CollectMode=inactive-or-failed
.
In addition, it is strongly recommended to set TimeoutStopSec=5
so that logout will not be delayed indefinitely in case the process does not stop properly.
gnome-session sets several environment variables for use by the session:
DISPLAY
This variable is set to the X display being used by
gnome-session. Note that if the --display
option is used this might be different from the setting of the environment
variable in gnome-session's environment.
Behavior of gnome-session ifself can be modified via the following environment variables:
GNOME_SESSION_AUTOSTART_DIR
This variable specifies a list of directories to the searched for
autostart files. This variable overrides all directories specified
via the --autostart
option, as well as all default autostart directories.
$XDG_CONFIG_HOME/autostart
$XDG_CONFIG_DIRS/autostart
/usr/share/gnome/autostart
Applications defined via .desktop
files in those
directories will be started on login.
$XDG_CONFIG_HOME/gnome-session/sessions
$XDG_CONFIG_DIRS/gnome-session/sessions
$XDG_DATA_DIRS/gnome-session/sessions
These directories contain the .session
files that
can be used with the --session
option.
$XDG_CONFIG_HOME/gnome-session/saved-sessions
This directory contains the list of applications of the saved session.