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

# budgie-session(1)

Start the budgie desktop environment

## NAME

budgie-session - Start the budgie desktop environment

## SYNOPSIS

**budgie-session \[-a\|--autostart=DIR\] \[--session=SESSION\] \[--failsafe\|-f\] \[--debug\] \[--whale\]**

## DESCRIPTION

The *budgie-session* program starts up the budgie desktop environment. This command is typically executed by your login manager (either gdm, xdm, or from your X startup scripts). It will load either your saved session, or the default budgie installation on your system. Note that *budgie-session* is a wrapper script for *budgie-session-binary*.

**$XDG\_CONFIG\_HOME/budgie-session/sessions**, **$XDG\_CONFIG\_DIRS/budgie-session/sessions** and **$XDG\_DATA\_DIRS/budgie-session/sessions**.

When saving a session, *budgie-session* saves the currently running applications in the **$XDG\_CONFIG\_HOME/budgie-session/saved-session** directory. Saving sessions is only supported with the legacy non-systemd startup method.

*budgie-session* is an X11R6 session manager. It can manage budgie applications as well as any X11R6 SM compliant application.

## OPTIONS

The following options are supported:

- *--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, **budgie.session** will be used.

- *--builtin*

  Use the legacy non-systemd method of managing the user session.

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

## SESSION DEFINITION

Sessions are defined in **.session** files, that are using a .desktop-like format, with the following keys in the **budgie 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:

```
[budgie Session]
Name=budgie
RequiredComponents=budgie-desktop;gnome-settings-daemon;
```

The **.session** files are looked for in **$XDG\_CONFIG\_HOME/budgie-session/sessions**, **$XDG\_CONFIG\_DIRS/budgie-session/sessions** and **$XDG\_DATA\_DIRS/budgie-session/sessions**.

It is best to use *--builtin* if session customizations are required. This is due to the way that budgie currently defines the components that will be started on each session type.

## ENVIRONMENT

*budgie-session* sets several environment variables for the use of its child processes:

**SESSION\_MANAGER**

-

  This variable is used by session-manager aware clients to contact budgie-session.

**DISPLAY**

-

  This variable is set to the X display being used by *budgie-session*. Note that if the *--display* option is used this might be different from the setting of the environment variable when budgie-session is invoked.

Behavior of *budgie-session* ifself can be modified via the following environment variable:

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

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

**$XDG\_CONFIG\_HOME/budgie-session/sessions** **$XDG\_CONFIG\_DIRS/budgie-session/sessions** **$XDG\_DATA\_DIRS/budgie-session/sessions**

-

  These directories contain the **.session** files that can be used with the *--session* option.

**$XDG\_CONFIG\_HOME/budgie-session/saved-session**

-

  This directory contains the list of applications of the saved session.

## BUGS

If you find bugs in the *budgie-session* program, please report these on https://github.com/buddiesofbudgie/budgie-session/issues.

## SEE ALSO

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