GNOME-SESSION(1)

✨ NAME ✨

okay so real quick — gnome-session is the manual page GNOME-SESSION(1), and it does exactly one extremely iconic thing: it starts the GNOME desktop environment. periodt. 💅

---

🦋 SYNOPSIS 🦋

gnome-session [OPTION...]

---

🌸 DESCRIPTION 🌸

gnome-session starts up the whole entire GNOME desktop environment. bestie, this is the program that makes your screen become GNOME. ✨

It's normally launched for you by your login manager — so like GDM, SDDM, lightdm, or whatever other one you're running. You're usually not typing this yourself, it just happens when you log in. 🫶

When it runs, it will either load your saved session, or it will give you a default session for the user — and that default is defined by the system administrator (or, you know, whatever the default GNOME installation on your system ships with).

The default session lives in gnome.session, which is a .desktop-like file. Here's where it goes looking for it: 🔍

• $XDG_CONFIG_HOME/gnome-session/sessions
• $XDG_CONFIG_DIRS/gnome-session/sessions
• $XDG_DATA_DIRS/gnome-session/sessions

---

💖 OPTIONS 💖

• --session=SESSION — runs the applications defined in SESSION.session. If you don't pass this at all, gnome.session gets used instead. no thoughts, just defaults. 🎀
• --debug — turns on debugging code. for when you wanna see the whole tea. 🍵

---

👑 SYSTEMD 👑

ngl, this part is kind of the main character. gnome-session uses systemd for the bulk of its service management — that's just how it does things now. 💫

systemd provides two special targets for desktop integration:

• graphical-session.target
• graphical-session-pre.target

These two work across desktop environments, so use them if you possibly can. fr fr, that's the recommendation.

On top of that, gnome-session gives you these extra GNOME-specific targets:

• gnome-session.target — a generic unit that stays active throughout the entire session. it's basically the sibling of graphical-session.target.
• gnome-session-pre.target — for tasks that need to happen before session startup. the sibling of graphical-session-pre.target.
• gnome-session@SESSION.target — the main unit that gets started for the session. SESSION here is set according to whatever session got passed in through --session.
• gnome-session-basic-services.target — a special unit listing the basic services needed by any GNOME session built around gnome-shell. this one exists so kiosk sessions — like the GDM login screen — can conveniently reuse it. 🧚
• gnome-session-x11-services.target — a special unit that starts up when X11 services are needed. heads up: programs will need to use the special GNOME_SETUP_DISPLAY environment variable instead of DISPLAY. yes really, not DISPLAY. 🙈

⚠️ now listen, bestie, this is the part where you have to be careful: you must take care to set appropriate After= rules. And it's strongly recommended that you always do that in combination with BindsTo= or PartOf= on one of the core targets (for example graphical-session.target).

⚠️ also: units are required to set CollectMode=inactive-or-failed. and on top of that, it is strongly recommended to set TimeoutStopSec=5, so that logout doesn't get delayed indefinitely in case the process doesn't stop properly. don't skip this one, you'll be sitting there waiting to log out forever. 💀

---

🌈 SESSION DEFINITION 🌈

Sessions are defined in .session files, and those use a .desktop-like format. Inside them, in the GNOME Session group, you get these keys:

• Name — the name of the session. this one can be localized. 🌍
• Kiosk — okay so kiosk sessions are these special single-purpose sessions built around starting one specific app. like, a kiosk session might run a full-screen web browser that's locked to one specific page. in GNOME we use kiosk sessions for the login screen (where the app is the login screen UI) and for the initial-setup first boot experience. when this is set to true, gnome-session will make no attempt to autostart any .desktop files at all — instead it will require that the session configures all required functionality via systemd. all of it. no autostart, not even a little. 👑

Here's 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
• $XDG_DATA_DIRS/gnome-session/sessions

Important vibe check: session definitions don't do anything on their own. they're nothing without systemd configuration to actually provide functionality (i.e. launch services). the recommended way to do that is by hooking into one of the targets described above. 💫

For instance: when you're 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. literally that easy. 🎀

---

🍓 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. 📌 but ngl, note this: previous versions of gnome-session would launch services from here, and that is no longer the case. services should now be configured via systemd unit files. the old way is over, we've moved on. 💅

$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 you can use with the --session option. 🌸

---

😭 BUGS 😭

If you find bugs in the gnome-session program, please report them here: https://gitlab.gnome.org/GNOME/gnome-session/issues. do it, they wanna know. 🫶

---

⭐ SEE ALSO ⭐

gnome-session-quit(1)

---

and that's the whole page, bestie!! this was gnome-session from GNOME-SESSION(1) — yes, the manual is literally named the same thing as the program, iconic behavior honestly. go forth, log in, and let systemd handle the rest. mwah 💖✨🎀🦋🌸