---
name: "gnome-session"
section: "1"
platform: "linux"
package: "gnome-session"
version: "51.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gnome-session"
---

# gnome-session(1)

Start the GNOME desktop environment

## NAME

gnome-session - Start the GNOME desktop environment

## SYNOPSIS

**gnome-session** \[OPTION...\]

## DESCRIPTION

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).

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.

## OPTIONS

- **--session**=SESSION

  Use the applications defined in SESSION.session. If not specified, gnome.session will be used.

- **--debug**

  Enable debugging code.

## SYSTEMD

**gnome-session** uses **systemd** for the bulk of its service management. **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@SESSION.target

Main unit started for the session. *SESSION* is set according to the session that is passed in via **--session**.

gnome-session-basic-services.target

Special unit that lists basic services that are needed by any GNOME session built around **gnome-shell**. This allows for convenient reuse by kiosk sessions like the GDM login screen.

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.

## SESSION DEFINITION

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.

*Kiosk*

Kiosk sessions are special single-purpose sessions that are built around starting some specific app. For instance, a kiosk session may run a full-screen web browser that's locked to a specific page. In GNOME, we use kiosk sessions for the login screen (where the app is the login screen UI) and the initial-setup first boot experience. When set to true, **gnome-session** will make no attempt to autostart any .desktop files, and will instead require that the session configures all required functionality via systemd.

Here is an example of a session definition:

```
[GNOME Session]
Name=GNOME
```

The .session files are loaded from $XDG\_CONFIG\_HOME/gnome-session/sessions, $XDG\_CONFIG\_DIRS/gnome-session/sessions and $XDG\_DATA\_DIRS/gnome-session/sessions.

Session definitions don't do anything on their own, and they need to be accompanied by **systemd** configuration to provide some functionality (i.e. launch services). The recommended way to do that is by hooking into one of the targets described above. For instance: when defining a session named foobar, you can create a systemd drop-in file in /etc/systemd/user/gnome-session@foobar.target.d/session.conf and define Requires= and Wants= dependencies to tell systemd what services it needs to start when launching this session.

## FILES

```
      $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. Note that previous versions of **gnome-session** would launch services from here, but this is no longer the case. Services should now be configured via **systemd** unit files

```
      $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.

## BUGS

If you find bugs in the **gnome-session** program, please report these on https://gitlab.gnome.org/GNOME/gnome-session/issues.

## SEE ALSO

[**gnome-session-quit**(1)](/gnome-session-quit/1.md)