# GNOME

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Related articles

- Desktop environment
- GTK
- GDM
- GNOME/Tips and tricks
- GNOME/Troubleshooting
- GNOME/Files
- GNOME/Gedit
- GNOME/Web
- GNOME/Evolution
- GNOME/Flashback
- GNOME/Keyring
- GNOME/Document viewer
- Official repositories#gnome-unstable

GNOME (/(ɡ)noʊm/) is a desktop environment that aims to be simple and easy to use. It is designed by The GNOME Project and is composed entirely of free and open-source software. The default display is Wayland instead of Xorg and the available sessions are

- GNOME, the default, runs GNOME Shell on Wayland. Traditional X applications are run through Xwayland.
- GNOME Classic provides a "traditional desktop experience" (with an interface similar to GNOME 2) by using certain extensions and values. Thus, it is a customized form of GNOME Shell rather than a truly distinct mode.
- GNOME on Xorg runs GNOME Shell using Xorg.

## Installation

Two groups are available:

- gnome contains the base GNOME desktop and a subset of well-integrated applications;
- gnome-extra contains further GNOME applications, including an email client, an IRC client, GNOME Tweaks, and a set of games. Note that this group builds on the gnome group.

The base desktop consists of GNOME Shell, a plugin for the Mutter window manager. It can be installed separately with gnome-shell.

Note: mutter acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter. The GNOME session manager automatically detects if your video driver is capable of running GNOME Shell and if not, falls back to software rendering using llvmpipe.

Unstable releases can also be used, see Official repositories#gnome-unstable.

## Starting

GNOME can be started either graphically with a display manager or manually from the console (some features may be missing). The display manager included in gnome is GDM.

Note: Support for screen locking (and more) in GNOME is provided by GDM. If GNOME is not started with GDM, another screen locker may be used. See List of applications/Security#Screen lockers.

### Graphically

If you installed the gnome group and want GNOME to start automatically on next boot, enable `gdm.service`. You can then select the desired session: GNOME, GNOME Classic (only displayed if gnome-shell-extensions is installed), or GNOME on Xorg from the display manager's session menu.

If you prefer to start GNOME right away, thereby avoiding a reboot, start the aforementioned `gdm.service` from a graphically unoccupied tty instead.

### Manually

#### Xorg sessions

- For the GNOME on Xorg session, add to the `~/.xinitrc` file (see [1] for details):

      export XDG_SESSION_TYPE=x11
      export GDK_BACKEND=x11
      exec gnome-session

- For the GNOME Classic session, add to the `~/.xinitrc` file:

      export XDG_CURRENT_DESKTOP=GNOME-Classic:GNOME
      export GNOME_SHELL_SESSION_MODE=classic
      exec gnome-session

After editing the `~/.xinitrc` file, GNOME can be launched with the `startx` command (see xinitrc for additional details, such as preserving the logind session). After setting up the `~/.xinitrc` file it can also be arranged to Start X at login, e.g. on tty1 by adding to `.bash_profile`:

    if [[ -z $DISPLAY && $(tty) == /dev/tty1 ]]; then
      XDG_SESSION_TYPE=x11 GDK_BACKEND=x11 exec startx
    fi

#### Wayland sessions

The factual accuracy of this article or section is disputed.

Reason: Executing `gnome-session` via dbus may cause issues or not work at all. Some issues include the inability to start Chrome/Chromium and the lack of a sound device. Running `gnome-session` directly may work better. (Discuss in Talk:GNOME#Manually start a Wayland session)
Note: An X server is still necessary to run applications that have not yet been ported to Wayland, see Wayland#XWayland for details. Applications using certain graphics libraries, such as Qt, can be forced to use Wayland by setting environment variables. See Wayland#GUI libraries for more information.

Manually starting a Wayland session is possible with `XDG_SESSION_TYPE=wayland dbus-run-session gnome-session`. Alternatively, call `gnome-shell` directly with its wayland flag from any available tty:

    $ gnome-shell --wayland

Note that manual invocation of Gnome does not require `gdm` (consequently also the accompanying `gdm.service`) at all and is thus also accessible for users with a (possibly very) minimal installation of Gnome composing of a selected few packages included in the more inclusive `gnome` group in accordance to personal preference.

To start on login to tty1, add the previous line of code to your `.bash_profile`. Firefox and QT applications do not respect `XDG_SESSION_TYPE`, so add variables for them as well:

    if [[ -z $DISPLAY && $(tty) == /dev/tty1 && $XDG_SESSION_TYPE == tty ]]; then
      MOZ_ENABLE_WAYLAND=1 QT_QPA_PLATFORM=wayland XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session
    fi

### GNOME applications in Wayland

When the GNOME session is used, GNOME applications will be run using Wayland. For debugging cases, GTK3 manual and GTK4 manual list options and environment variables.

## Navigation

To learn how to use the GNOME shell effectively read the GNOME Shell Cheat Sheet; it highlights GNOME shell features and keyboard shortcuts. Features include task switching, keyboard use, window control, the panel, overview mode, and more. A few of the shortcuts are:

- `Super+m`: show notification list
- `Super+a`: show application grid
- `Alt+Tab`: cycle active applications
- `Alt+`` (the key above `Tab` on US keyboard layouts): cycle windows of the application in the foreground
- `Alt+F2`, then enter `r` or `restart`: restart the shell in case of graphical shell problems (only in X/legacy mode, not in Wayland mode).

See Keyboard navigation for more shortcuts.

Tip: To make `Alt+Tab` switch applications only in current workspace, you can set `current-workspace-only` to `true`:

    $ gsettings set org.gnome.shell.app-switcher current-workspace-only true

## Legacy names

Note: Some GNOME programs have undergone name changes where the application's name in documentation and about dialogs has been changed but the executable name has not. A few such applications are listed in the table below.
Tip: Searching for the legacy name of an application in the Shell search bar will successfully return the application in question. For instance, searching for nautilus will return Files.

Current | Legacy
--- | ---
Files | Nautilus
Web | Epiphany
Videos | Totem
Main Menu | Alacarte
Document Viewer | Evince
Disk Usage Analyzer | Baobab
Image Viewer | EoG (Eye of GNOME)
Passwords and Keys | Seahorse
GNOME Translation Editor | Gtranslator

## Configuration

GNOME Settings (gnome-control-center) and GNOME applications use the dconf configuration system to store their settings.

You can directly access the dconf database using the gsettings(1) command line tool. This also allows you to configure settings not exposed by the user interfaces. Command line tool dconf(1) can directly modify the underlying database, bypassing validation.

Up until GNOME 3.24, settings were applied by the GNOME settings daemon (located at `/usr/lib/gnome-settings-daemon/gnome-settings-daemon`), which could be run outside of a GNOME session.

GNOME 3.24, however, replaced the GNOME settings daemon with several separate settings plugins `/usr/lib/gnome-settings-daemon/gsd-*` which were later moved to `/usr/lib/gsd-*`. These plugins are now controlled via desktop files under `/etc/xdg/autostart/` (matching `org.gnome.SettingsDaemon.*.desktop`). To run these plugins outside of a GNOME session, you will now need to copy/edit the appropriate desktop entries to `~/.config/autostart`.

The configuration is usually performed user-specific; this section does not cover how to create configuration templates for multiple users.

### System settings

#### Color

The daemon `colord` reads the display's EDID and extracts the appropriate color profile. Most color profiles are accurate and no setup is required; however for those that are not accurate, or for older displays, color profiles can be put in `~/.local/share/icc/` and directed to.

#### Night Light

GNOME comes with a built-in blue light filter similar to Redshift. You can enable and customise the time you want to enable Night Light from the display settings menu. Furthermore, you can tweak the kelvin temperature with the following dconf setting, where 5000 is an example value:

    $ gsettings set org.gnome.settings-daemon.plugins.color night-light-temperature 5000

Tip: To change the daytime temperature in a Wayland session, install the Night Light Slider extension.

#### Date & time

If the system has a configured Network Time Protocol daemon, it will be effective for GNOME as well. The synchronization can be set to manual control from the menu, if required.

GNOME supports automatic time zone selection (can be enabled in Date & Time section of the system settings, given that location services are enabled (see Privacy section of the settings).

To show the date in the top bar, execute:

    $ gsettings set org.gnome.desktop.interface clock-show-date true

Additionally, to show week numbers in the calendar opened on the top bar, execute:

    $ gsettings set org.gnome.desktop.calendar show-weekdate true

#### Default applications

Upon installing GNOME for the first time, you may find that the wrong applications are handling certain protocols. For example, totem opens videos instead of a previously used VLC. Some of the associations can be set from system settings via Default Applications.

For other protocols and methods see Default applications for configuration.

#### Mouse and touchpad

Most touchpad settings can be set from system settings via Mouse & Touchpad.

Depending on your device, other configuration settings may be available, but not exposed via the default GUI. For example, a different touchpad `click-method`

    $ gsettings range org.gnome.desktop.peripherals.touchpad click-method

    enum
    'default'
    'none'
    'areas'
    'fingers'

to be set manually:

    $ gsettings set org.gnome.desktop.peripherals.touchpad click-method 'fingers'

or via gnome-tweaks.

Note: The synaptics driver is not supported by GNOME. Instead, you should use libinput. See this bug report.

#### Network

NetworkManager is the native tool of the GNOME project to control network settings from the shell, and is part of gnome group. If not installed already, install the networkmanager package and enable the `NetworkManager.service` systemd unit.

While any other network manager can be used as well, NetworkManager provides the full integration via the shell network settings and a status indicator applet network-manager-applet (not required for GNOME).

Note: Hidden wireless networks set up with networkmanager's nmtui do not connect automatically. You need to create a new profile using GNOME control center in order to restore auto-connect capabilities for that network.

#### Online accounts

Some online accounts, such as ownCloud, require gvfs-goa to be installed for full functionality in GNOME applications such as GNOME Files and GNOME Documents [2].

See Online accounts for more information.

#### Search

The GNOME shell has a search that can be quickly accessed by pressing the `Super` key and starting to type. The tracker package is installed by default as a part of gnome group and provides an indexing application and metadata database. It can be configured with the Search and Indexing menu item; monitor status with tracker-control. It is started automatically by gnome-session when the user logs in. Indexing can be started manually with `tracker-control -s`. Search settings can also be configured in Settings.

The Tracker database can be queried using the tracker-sparql command. See tracker-sparql(1) for more information.

### Advanced settings

As noted above, many configuration options such as changing the GTK theme or the window manager theme are not exposed in GNOME Settings (gnome-control-center). Those users that want to configure these settings may wish to use the GNOME Tweaks (gnome-tweaks), a convenient graphical tool which exposes many of these settings.

GNOME settings (which are stored in the DConf database) can also be configured using the dconf-editor(1) (a graphical DConf configuration tool) or the gsettings command line tool. The GNOME Tweaks does not do anything else in the background of the GUI; note though that you will not find all settings described in the following sections in it.

#### Appearance

##### Themes

GNOME uses Adwaita by default. To apply Adwaita dark only to GTK 2 applications use the following symlink:

    $ ln -s /usr/share/themes/Adwaita-dark ~/.themes/Adwaita

To select new themes (move them to the appropriate directory and) use GNOME Tweaks or the GSettings commands below:

For the GTK theme:

    $ gsettings set org.gnome.desktop.interface gtk-theme theme-name

For the icon theme:

    $ gsettings set org.gnome.desktop.interface icon-theme theme-name

Note: The window manager theme follows the GTK theme. Using `org.gnome.desktop.wm.preferences theme` is deprecated and ignored.

See GTK#Themes and Icons#Manually.

##### Titlebar height

Note: Applying this configuration shrinks the titlebar of applications that do not use GNOME-style CSD. Native GNOME applications with CSD are not affected.

    ~/.config/gtk-3.0/gtk.css

    headerbar.default-decoration {
     padding-top: 5px;
     padding-bottom: 5px;
     min-height: 0px;
     font-size: 0.8em;
    }

    headerbar.default-decoration button.titlebutton {
     padding: 0px;
     min-height: 0px;
    }

See [3] for more information.

##### Titlebar button order

To set the order for the GNOME window manager (Mutter, Metacity):

    $ gsettings set org.gnome.desktop.wm.preferences button-layout ':minimize,maximize,close'

Tip: The colon indicates which side of the titlebar the window buttons will appear.

##### Hide titlebar when maximized

- Install gnome-shell-extension-gtktitlebar-gitAUR. Removes titlebars of maximized, non-GTK windows.
- Install gnome-shell-extension-no-title-bar-gitAUR or gnome-shell-extension-no-title-barAUR. Maximized windows get the title bar merged into the activity bar.

Note: The above extension does not work for gnome-shell version 3.32 or higher [4].

- Install mutter-hide-legacy-decorationsAUR. It changes a default setting in the window manager, so as to automatically hide the titlebar on legacy (non-headerbar) apps when they are maximized or tiled to the side.
- Install gnome-shell-extension-pixel-saver-gitAUR or gnome-shell-extension-pixel-saverAUR. Maximized windows get the title bar merged into the activity bar, saving precious pixels.

##### GNOME Shell themes

The theme of GNOME Shell itself is configurable. To use a Shell theme, firstly ensure that you have the gnome-shell-extensions package installed. Then enable the User Themes extension, either through the GNOME Extensions application or through the GNOME Shell Extensions webpage. Shell themes can then be loaded and selected using GNOME Extensions.

There are a number of GNOME Shell themes available in the AUR. Shell themes can also be downloaded from gnome-look.org.

##### AppIndicators/Top bar icons

To enable AppIndicators, which is useful for controlling/monitoring certain applications running in the background, Install gnome-shell-extension-appindicator or gnome-shell-extension-appindicator-gitAUR, restart the GNOME Shell, then enable the AppIndicator extension in the GNOME Extensions application or by running `$ gnome-extensions enable $(gnome-extensions list | grep -m 1 appindicatorsupport)`.

#### Apps grid folders

Tip: The gnome-catgen (gnome-catgen-gitAUR) script allows you to manage folders through the creation of files in `~/.local/share/applications-categories` named after each category and containing a list of the desktop files belonging to apps you would like to have inside. Optionally, you can have it cycle through each app without a folder and input the desired category until you `Ctrl+c` or run out of apps.

In the dconf-editor navigate to `org.gnome.desktop.app-folders` and set the value of `folder-children` to an array of comma separated folder names:

    ['Utilities', 'Sundry']

Add applications using `gsettings`:

    $ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ apps "['alacarte.desktop', 'dconf-editor.desktop']"

This adds the applications `alacarte.desktop` and `dconf-editor.desktop` to the Sundry folder. This will also create the folder `org.gnome.desktop.app-folders.folders.Sundry`.

To name the folder (if it has no name that appears at the top of the applications):

    $ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ name "Sundry"

Applications can also be sorted by their category (specified in their .desktop file):

    $ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ categories "['Office']"

If certain applications matching a category are not wanted in a certain folder, exclusions can be set:

    $ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ excluded-apps "['libreoffice-draw.desktop']"

For more information, see [5] and Gentoo:Gnome Applications Folders.

#### Autostart

GNOME implements XDG Autostart.

The gnome-tweaks allows managing autostart-entries.

Tip: If the plus sign button in the Tweaks's Startup Applications section is unresponsive, try start the Tweaks from the terminal using the following command: `gnome-tweaks`. See the following forum thread.
Note: The deprecated gnome-session-properties dialog can be added by installing the gnome-session-propertiesAUR package.

#### Desktop

##### Icons on the desktop

Up until GNOME 3.28, icons on the desktop were provided by Files which would draw a transparent window over the desktop containing the icons. As of GNOME 3.28 this functionality has been removed and desktop icons are no longer available in GNOME. Possible workarounds include using Nemo (a fork of Files which still has desktop icons functionality) or installing gnome-shell-extension-desktop-iconsAUR, which replicates the desktop icon functionality available in GNOME 3.26 and prior, but with some minor differences. For more information, please see the following Arch forum thread.

##### Lock screen and background

When setting the Desktop or Lock screen background, it is important to note that the Pictures tab will only display pictures located in `/home/username/Pictures` folder. If you wish to use a picture not located in this folder, use the commands indicated below.

For the desktop background:

    $ gsettings set org.gnome.desktop.background picture-uri 'file:///path/to/my/picture.jpg'

For the lock screen background:

    $ gsettings set org.gnome.desktop.screensaver picture-uri 'file:///path/to/my/picture.jpg'

##### Disable top left hot corner

Starting from GNOME 3.34 you can disable it with this:

    $ gsettings set org.gnome.desktop.interface enable-hot-corners false

or via gnome-tweaks, in Top Bar > Activities Overview Hot Corner

##### Startup in Overview Mode

Starting from GNOME 40, the desktop will start directly into Overview Mode instead of an empty desktop (like in previous versions). To mimic legacy behaviour, one may install the extension No overview at start-up.

See the discussion at [6].

#### Extensions

The catalogue of extensions is available at https://extensions.gnome.org. They can be installed and activated in a browser by setting the switch in the top left of the screen to ON and clicking Install on the popup window (if the extension in question is not installed). Installed extensions may be seen at https://extensions.gnome.org/local/, where available updates can be checked. Installed extensions can also be enabled or disabled through a GUI with gnome-extensions-app or from the command line with gnome-extensions(1).

Note: Installing extensions from https://extensions.gnome.org using a browser requires the installation of chrome-gnome-shellAUR and the appropriate browser extension.

GNOME Shell can be customized with extensions per user or system-wide. Installing extensions with pacman makes them available for all users of the system and automates the update process.

The gnome-shell-extensions package provides a set of extensions maintained as part of the GNOME project (many of the included extensions are used by the GNOME Classic session). Users who want a taskbar but do not wish to use the GNOME Classic session may want to enable the Window list extension (provided by the aforementioned package).

To list currently enabled extensions:

    $ gsettings get org.gnome.shell enabled-extensions

The above command may list extensions that have been removed. To only list extensions that are enabled and installed, use gnome-extensions instead:

    $ gnome-extensions list --enabled

For more information about GNOME shell extensions, see https://extensions.gnome.org/about/.

#### Fonts

Tip: If you set the Scaling factor to a value above 1.00, the Accessibility menu will be automatically enabled.

Fonts can be set for Window titles, Interface (applications), Documents and Monospace. See the Fonts tab in the Tweaks for the relevant options.

For hinting, RGBA will likely be desired as this fits most monitors types, and if fonts appear too blocked reduce hinting to Slight or None.

#### WEBP, thumbnails

Install webp-pixbuf-loader to make GNOME's image viewer (eog) work with WEBP images, and add a thumbnailer which creates thumbnails for WEBP images to display them in GNOME Files.

#### Input methods

GNOME has integrated support for input methods through IBus. Only ibus and the wanted input method engine (e.g. ibus-libpinyin for Intelligent Pinyin) needed to be installed. After installation, the input method engine can be added as a keyboard layout under Keyboard > Input Sources in GNOME Settings (gnome-control-center).

#### Keyboard Layout quirks

If you are using an alternative keyboard layout like Neo2 which uses multiple layers/modifiers, you might need to go to Keyboard > Type Special Characters in GNOME Settings (gnome-control-center) and change the Alternate Characters Key away from Right Alt so that it can be used as a native modifier of the keyboard layout. Setting it to e.g. Left Alt prevents Alt+Tab, so be careful what you change it to. Without this change, your left Mod3 key might work, but the right one (AltGr) does not. (As of 2021-05-18)

#### Power

When you are using a laptop you might want to alter the following settings controlling behavior when idle, screen lock power button presses and lid close:

    $ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout 3600
    $ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type hibernate
    $ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout 1800
    $ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type hibernate
    $ gsettings set org.gnome.settings-daemon.plugins.power power-button-action suspend
    $ gsettings set org.gnome.desktop.lockdown disable-lock-screen true

To keep the monitor active when the lid is closed:

    $ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing

GNOME 3.24 deprecated the following settings:

    org.gnome.settings-daemon.plugins.power button-hibernate
    org.gnome.settings-daemon.plugins.power button-power
    org.gnome.settings-daemon.plugins.power button-sleep
    org.gnome.settings-daemon.plugins.power button-suspend
    org.gnome.settings-daemon.plugins.power critical-battery-action

##### Do not suspend when laptop lid is closed

The settings panel of GNOME does not provide an option for the user to change the action triggered when the laptop lid is closed. However gnome-tweaks can override the setting applied by systemd. On the tab General turn off the switch Suspend when laptop lid is closed. The system will then not Suspend to RAM (S3) on lid close.

To change the lid switch action system-wide, ensure that the setting described above is not turned off and edit the systemd settings in `/etc/systemd/logind.conf`. To turn off suspend on lid close, set `HandleLidSwitch=ignore`, as described in Power management#ACPI events.

##### Change critical battery level action

The settings panel does not provide an option for changing the critical battery level action. These settings have been removed from dconf as well. They are now managed by upower. Edit the upower settings in `/etc/UPower/UPower.conf`. Find these settings and adjust to your needs.

    /etc/UPower/UPower.conf

    PercentageLow=10
    PercentageCritical=3
    PercentageAction=2
    CriticalPowerAction=HybridSleep

### Use a different window manager

GNOME Shell does not support using a different window manager, however GNOME Flashback provides sessions for Metacity and Compiz. Furthermore, it is possible to define your own custom GNOME sessions which use alternative components.

## See also

- Official Website
- Contributing to GNOME, feature requests, bugs, code
- Wikipedia article
- GNOME-Shell Extensions
- GNOME Shell Cheat Sheet
- Customization (themes, icons...):
  - Personalize GNOME
  - GNOME Look
- GNOME applications:
  - GNOME Apps Index
  - Wikipedia:GNOME Core Applications
- GNOME Source/Mirrors:
  - GNOME GitLab
  - GNOME Github Mirror

Category:

- GNOME

Hidden category:

- Pages or sections flagged with Template:Accuracy