From ArchWiki
Jump to navigation Jump to search


GNOME (pronounced gah-nohm or nohm) 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. GNOME is a part of the GNU Project.



Two groups are available from the official repositories:

  • gnome contains the base GNOME desktop and a subset of well-integrated applications;
  • gnome-extra contains further GNOME applications, including an archive manager, disk manager, text editor, 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.

Additional packages

These packages are not in the above mentioned groups:

  • Boxes — A simple user interface to access libvirt virtual machines. || gnome-boxes
  • GNOME Initial Setup — A simple, easy, and safe way to prepare a new system. || gnome-initial-setup
  • GNOME PackageKit — Collection of graphical tools for PackageKit to be used in the GNOME desktop. || gnome-packagekit || nemiver
  • Software — Lets you install and update applications and system extensions. || gnome-software

GNOME Sessions

GNOME has three available sessions, all using GNOME Shell.

  • GNOME is the default, innovative layout.
  • GNOME Classic is a traditional desktop layout with a similar interface to GNOME 2, using pre-activated extensions and parameters. [1] Hence it is more a customized GNOME Shell than a truly distinct mode.
  • GNOME on Wayland runs GNOME Shell using the new Wayland protocol. Traditional X applications are run through Xwayland.

Starting GNOME

GNOME can be started either graphically, using a display manager, or manually from the console. For optimal desktop integration, using GDM (the GNOME Display manager) is recommended. Note that enabling a display manager (such as GDM) means that Xorg will run with root rights.

Note: Support for screen locking in GNOME is provided by GDM. If GNOME is not started using GDM, you will have to use another screen locker to provide this functionality - see List of applications/Security#Screen lockers.


Select the session: GNOME, GNOME Classic or GNOME on Wayland from the display manager's session menu.


  • For the standard GNOME session, add to the ~/.xinitrc file: exec gnome-session.
  • For the GNOME Classic session, add to the ~/.xinitrc file: exec env GNOME_SHELL_SESSION_MODE=classic gnome-session --session gnome-classic.

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.

Note: GNOME on Wayland requires the xorg-server-xwayland package, and cannot be started using startx and ~/.xinitrc. Instead, run gnome-session --session=gnome-wayland.

For more information, see Wayland.

GNOME applications in Wayland

Currently, by default, GNOME applications will be run as traditional X applications through Xwayland. To test GNOME applications with Wayland, use the command line to run the application and prefix the command with env GDK_BACKEND=wayland <command>.

Note: Setting a global Wayland environment, by running env GDK_BACKEND=wayland gnome-session --session=gnome-wayland, currently does not work - gnome-session will exit immediately.

See the following page for the status of GNOME Applications under Wayland.


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 message tray
  • Super + a: show applications menu
  • 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.

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 Analyser Baobab
Image Viewer EoG (Eye of GNOME)
Passwords and Keys Seahorse


The GNOME desktop relies on a configuration database backend (DConf) to store system and application settings. The desktop comes with default configuration settings, installed applications add their own to the database. The basic configuration is done either via the GNOME System Settings panel (gnome-control-center) or the preferences of the individual applications. A direct configuration of the DConf database is always possible as well and performed with the gsettings command line tool. In particular it can be used to configure settings which are not exposed via the user interface,

The configuration is usually performed per user and the rest of this section does not cover how to create configuration templates for a multi-user-system.

System settings

Control panel settings of note.


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 dislplays, color profiles can be put in ~/.local/share/icc/ and directed to.

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.

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 Shell calendar, execute:

$ gsettings set 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: System > Details > Default applications.

For other protocols and methods see Default applications for configuration.

Mouse and touchpad

To help reduce touchpad interference you may wish to implement the settings below:

  • Disable touchpad while typing
  • Disable scrolling
  • Disable tap-to-click


NetworkManager is the native tool of the GNOME project to control network settings from the shell. 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 (nm-applet). It is not part of the gnome and gnome-extra groups and must be installed separately, if desired.

Online accounts

Backends for the GNOME messaging application empathy as well as the GNOME Online Accounts section of the System Settings panel are provided in a separate group: telepathy. See #Unable to add accounts in Empathy and GNOME Online Accounts.


The GNOME shell has a search that can be quickly accessed by pressing the Super key and starting to type. For the search tracker must be installed, which 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 the System Settings panel.

The Tracker database can be queried using the tracker-sparql command. View its manual page man tracker-sparql 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 the GNOME System Settings panel (gnome-control-center). Those users that want to configure these settings may wish to use the GNOME Tweak Tool (gnome-tweak-tool), 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 (a graphical DConf configuration tool) or the gsettings command line tool. The GNOME Tweak Tool 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.


GTK+ themes and icon themes

To install a new theme or icon set, add the relevant ~/.local/share/themes or ~/.local/share/icons respectively (add to /usr/share/ instead of ~/.local/share/ for the themes to be available systemwide.) They and other GUI settings can also be defined in ~/.config/gtk-3.0/settings.ini:

gtk-theme-name = Adwaita
# next option is applicable only if selected theme supports it
gtk-application-prefer-dark-theme = true
# set font name and dimension
gtk-font-name = Sans 10

Additional theme locations:

Once installed, they can be selected using the GNOME Tweak Tool or GSettings - see below for GSettings commands:

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
Global dark theme

GNOME will use the Adwaita light theme by default however a dark variant of this theme (called the Global Dark Theme) also exists and can be selected using the Tweak Tool. Some applications such as Image Viewer (eog) use the dark theme by default. It should be noted that the Global Dark Theme only works with GTK+ 3 applications; some GTK+ 3 applications may only have partial support for the Global Dark theme. Qt and GTK+ 2 support for the Global Dark Theme may be added in the future.

Window manager themes

The window manager theme (the style of the window titlebars) can be set using the GNOME Tweak Tool or the following GSettings command:

$ gsettings set org.gnome.desktop.wm.preferences theme theme-name
Titlebar height
Note: As of GNOME 3.16, Mutter no longer uses Metacity themes. Instead, the titlebar decorations are themed using GTK+.

To change the titlebar height, create the following file, adjusting the padding as desired:

.header-bar.default-decoration {
    padding-top: 3px;
    padding-bottom: 3px;

.header-bar.default-decoration .button.titlebutton {
    padding-top: 2px;
    padding-bottom: 2px;

The titlebar height can also be reduced by selecting a smaller font. By default, the font is set to Cantarell Bold 11. You may wish to set the font to something smaller such as Sans Bold 10. You can do so using the following GSettings command:

$ gsettings set org.gnome.desktop.wm.preferences titlebar-font 'Sans Bold 10'
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.
Titlebar hide when maximized

Install maximusAUR from the AUR. To start the application, execute maximus from a terminal. When running, the daemon will automatically maximize windows. It will undecorate maximized windows and redecorate them when they are unmaximized. If you do not want all windows to start maximized, run maximus -m instead. Note that this will only work with windows decorated by the window manager; applications that use client-side decoration such as GNOME Files will not be undecorated when maximized.

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 GNOME Tweak Tool or through the GNOME Shell Extensions webpage. Shell themes can then be loaded and selected using the GNOME Tweak Tool.

There are a number of GNOME Shell themes available in the AUR.

Shell themes can also be downloaded from


Various Desktop settings can be applied.

Icons on the Desktop

See GNOME Files#Desktop Icons.

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'


Note: The GNOME Shell browser plugin which allows users to install extensions from is not compatible with Chrome/Chromium versions 35 and over. Users wishing to install extensions from the webpage will have to use a compatible browser such as Firefox or GNOME Web.

GNOME Shell can be customized with extensions per user or system-wide.

The catalogue of extensions is available at By a user they can be installed and activated in the browser by setting the switch in the top left of the screen to ON and clicking Install on the resulting dialog (if the extension in question is not installed). After installation it is shown in the tab, which has to be visited as well to check for available updates. Installed extensions can also be enabled or disabled using gnome-tweak-tool.

More information about GNOME shell extensions is available on the GNOME Shell Extensions about page.

Installing extensions via a package 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 gnome-shell-extensions package).

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 in Gnome's Regional & Language Settings.


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 Tweak Tool 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.

Startup applications

Note: The gnome-session-properties dialog was removed as of GNOME 3.12. It can be added back by installing the gnome-session-propertiesAUR package from the AUR.
Tip: If the plus sign button in the Tweak Tool's Startup Applications section is unresponsive, try start the Tweak Tool from the terminal using the following command: gnome-tweak-tool. See the following forum thread.

To start certain applications on login, copy the relevant .desktop file from /usr/share/applications/ to ~/.config/autostart/.

The same effect can be achieved using the Tweak Tool.


The basic power settings that may want to be altered (these settings assume the user is using a laptop):

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

To keep a monitor active on lid close:

$ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing
Prevent Suspend-To-RAM (S3) when closing the LID

Not all important power settings are exposed in the Settings panel. Some general settings may be modified on the level of Systemd. Therefore it is necessary to edit the file /etc/systemd/logind.conf. Set the variable HandleLidSwitch on ignore to prevent Suspend on LID-CLOSE:


Then, either reboot or restart the logind service:

# systemctl restart systemd-logind
Change critical battery level action

The System Settings panel only allows the user to choose between Suspend or Hibernate. To choose another option such as Do Nothing open the dconf-editor and navigate to org.gnome.settings-daemon.plugins.power. Edit the "critical-battery-action" value to "nothing".

Sort applications into application (app) folders

Tip: The gnome-catgen (gnome-catgen-gitAUR in AUR) 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'd 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 and set the value of folder-children to an array of comma separated folder names:

['Utilities', 'Sundry']

Add applications using gsettings:

$ gsettings set 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

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

$ gsettings set name "Sundry"

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

$ gsettings set categories "['Office']"

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

$ gsettings set excluded-apps "['libreoffice-draw.desktop']"

For further information, refer to the app-folders schema.

Tips and tricks

Other GNOME system settings and tips.


Turn on NumLock on login

Run the following command:

$ gsettings set org.gnome.settings-daemon.peripherals.keyboard numlock-state on

Hotkey alternatives

A lot of hotkeys can be changed via system settings menu. For example, to re-enable the show desktop keybinding:

System settings > Keyboard > Shortcuts > Navigation > Hide all normal windows

However, certain hotkeys cannot be changed directly via system settings. In order to change these keys, use dconf-editor. An example of particular note is the hotkey Alt- + ` (the key above Tab on US keyboard layouts). In GNOME Shell it is pre-configured to cycle through windows of an application, however it is also a hotkey often used in the Emacs editor. It can be changed by opening dconf-editor and modifying the switch-group key found in org.gnome.desktop.wm.keybindings.

It is possible to manually change the keys via an application's so-called accel map file. Where it is to be found is up to the application: For instance, Thunar's is at ~/.config/Thunar/accels.scm, whereas Files's is located at ~/.config/nautilus/accels and ~/.gnome2/accels/nautilus on old release.

The file should contain a list of possible hotkeys, each unchanged line commented out with a leading ";" that has to be removed for a change to become active. For example to replace the hotkey used by Files to move files to the trash folder, change the line:

; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")

to this:

(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")

The file is regenerated regularly so do not comment the file. The uncommented line will stay but every comment you add will be lost.

Keyboard switch with command

To have keyboard shortcut Alt + Shift switch keyboards:

Open Gnome-Tweak-Tool (or Keyboard Settings, in GNOME 3.16) and set Typing > Modifiers-only input sources > select Alt-shift. For more information see also the forum thread.

XkbOptions keyboard options

Using the dconf-editor, navigate to the key named org.gnome.desktop.input-sources.xkb-options and add desired XkbOptions (e.g. caps:swapescape) to the list.

See /usr/share/X11/xkb/rules/xorg for all XkbOptions and /usr/share/X11/xkb/symbols/* for the respective descriptions.

Note: To enable the Ctrl+Alt+Backspace combination to terminate Xorg, use the gnome-tweak-tool from official repositories. Within the Tweak Tool, navigate to Typing > Key sequence to kill the X server and select the option Ctrl+Alt+Backspace from the dropdown menu.

De-bind Windows key

By default, the 'Windows key' will open the GNOME Shell overview mode. You can unbind this key by running the command below

$ gsettings set org.gnome.mutter overlay-key 'Foo'


GNOME provides a disk utility to manipulate storage drive settings. These are some of its features:

  • Enable write cache is a feature that most hard drives provide. Data is cached and allocated at chosen times to improve system performance. Not recommended unless the computer has a backup battery pack or is a laptop as data would be lost on power failure.
Settings > Drive Settings > Write Cache > On
  • Automatic Mount Options can mount drives and partitions that are GPT based - will use default, recommended options.
Warning: This setting erases related fstab entries
Partition Settings > Edit Mount Options > Automatic Mount Options > On

Hiding applications from the menu

Tip: Desktop entries can be hidden by editing the .desktop files themselves. See Desktop entries#Hide desktop entries.

Use the Main Menu application (provided by the alacarte package) to hide any applications you do not wish to show in the menu.

Screencast recording

GNOME features built-in screencast recording with the Ctrl + Shift + Alt + R key combination. A red circle is displayed in the bottom right corner of the screen when the recording is in progress. After the recording is finished, a file named Screencast from %d%u-%c.webm is saved in the Videos directory. In order to use the screencast feature the gst plugins need to be installed.


Default save directory:

$ gsettings set org.gnome.gnome-screenshot auto-save-directory file:///home/USER/Desktop

Check the gnome-screenshot manual page for more options.

Log out delay

To eliminate the default 60 second delay when logging out:

$ gsettings set org.gnome.SessionManager logout-prompt false

Disable animations

To disable Shell animations (such as "Show Applications" and the wave animation in the top left activities hot corner), run:

$ gsettings set org.gnome.desktop.interface enable-animations false

Retina (HiDPI) display support

Gnome introduced HiDPI support in version 3.10. If your display does not provide the correct screen size through EDID, this can lead to incorrectly scaled UI elements. As a workaround you can open dconf-editor and find the key scaling-factor in org.gnome.desktop.interface. Set it to 1 to get the standard scale.

Also see HiDPI.

Passwords and keys (PGP Keys)

You can use the Passwords and Keys program (seahorse) to create a PGP key as it is a front end for GnuPG and installs it as dependency. This may be useful in the future (for instance if to encrypt a file). Create a key as shown below (the process may take about 10 minutes):

File > New > PGP Key > Name > Email > Defaults > Passphrase.


Change default terminal size

The default size of a new terminal can be adjusted in the menu Edit > Profile preferences .

New terminals adopt current directory

By default new terminals open in the $HOME directory. To have new terminals adopt the current working directory: source /etc/profile.d/ Add the command to the shell configuration to retain the behaviour.

Pad the terminal

To pad the terminal (create a small, invisible border between the window edges and the terminal contents) create the file below:

TerminalScreen {
    padding: 10px 10px 10px 10px;
    -VteTerminal-inner-border: 10px 10px 10px 10px;

Disable blinking cursor

Since GNOME 3.8 and the migration to GSettings and DConf the key required to modify in order to disable the blinking cursor in the Terminal differs slightly in contrast to the old GConf key. To disable the blinking cursor in GNOME 3.8 and above use:

$ gsettings set org.gnome.desktop.interface cursor-blink false

To disable the blinking cursor in Terminal only use (make sure profile uid is correct one):

$ dconf write /org/gnome/terminal/legacy/profiles:/:b1dcc9dd-5262-4d8d-a863-c897e6d979b9/cursor-blink-mode "'off'"

Disable confirmation window when closing Terminal

The Terminal will always display a confirmation window when trying to close the window while one is logged in as root. To avoid this, execute the following:

$ gsettings set org.gnome.Terminal.Legacy.Settings confirm-close false

Middle mouse button

By default, GNOME 3 disables middle mouse button emulation regardless of Xorg settings (Emulate3Buttons). To enable middle mouse button emulation use:

$ gsettings set org.gnome.settings-daemon.peripherals.mouse middle-button-enabled true

Enable button and menu icons

Since GTK+ 3.10, the GSettings key 'menus-have-icons' has been deprecated. Icons in buttons and menus can still be enabled by setting the following overrides:

$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/ButtonImages': <1>, 'Gtk/MenuImages': <1>}"

Use custom colours and gradients for desktop background

To use custom colours and gradients for your desktop background, you will first need to set either a transparent picture or else a non-existent picture as your desktop background. For instance, the command below will set a non-existent picture as the background.

$ gsettings set org.gnome.desktop.background picture-uri none

At this point, the desktop background should be a flat colour - the default colour setting is for a deep blue.

For a different flat colour you need only change the primary colour setting:

$ gsettings set org.gnome.desktop.background primary-color <my color>

where <my color> is a hex value (such as ffffff for white).

For a colour gradient, you will also need to change secondary colour setting org.gnome.desktop.background secondary-color and select a shading type. For instance, if you want a horizontal gradient, execute the following:

$ gsettings set org.gnome.desktop.background color-shading-type horizontal

If you are using a transparent picture as your background, you can set the opacity by executing the following:

$ gsettings set org.gnome.desktop.background picture-opacity <value>

where value is a number between 1 and 100 (100 for maximum opacity).

Transitioning backgrounds

GNOME can transition between different wallpapers at specific time intervals. This is done by creating an XML file specifying the pictures to be used and the time interval. For more information on creating such files, see the following article.

Alternatively, a number of tools are available to automate the process:

  • mkwlppr — This script creates XML files that can act as dynamic wallpapers for GNOME by referring to multiple wallpapers. || see mkwlppr
  • Wallpapoz — Wallpapoz is a tool that provides dynamic wallpapers for GNOME and Xfce desktops. || wallpapozAUR
  • CreBS — A Python/GTK application used to create and set desktop wallpaper slideshows for GNOME. || crebsAUR

For setting the XML file as the default background, see #Lock screen and background.


Shell freezes

In the event of a Shell freeze (which might be caused by certain appearance tweaks, malfunctioning extensions or perhaps a lack of available memory) restarting the Shell by pressing Alt + F2 and then entering r may not be possible.

In this case, try switching to another TTY (Ctrl + Alt + F2) and entering the following command: pkill -HUP gnome-shell. It may take a few seconds before the Shell successfully restarts. Restarting the shell in this fashion should not log the user out but it is a good idea to try and ensure that all work is saved anyway.

If this fails, the Xorg server will need to be restarted either by: pkill X for console logins or: systemctl restart gdm for GDM logins. Bear in mind that restarting the Xorg server will log the user out so try to ensure that all work is saved before attempting this.

Incorrect application defaults

When installing applications for the first time you may find that GNOME has the wrong application associated to a certain protocols - for instance, easytag becomes the folder handler instead of GNOME Files.

For GNOME Files see the following page: GNOME Files#Files is no longer the default file manager.

For Document Viewer, run the following command:

$ xdg-mime default evince.desktop application/pdf

For other applications, default handler settings are detailed on the following page: Default applications.

Optionally, you can install gnome-defaults-listAUR from the AUR. It will place your configuration file at /etc/gnome/defaults.list.

Tracker & Documents do not list any local files

In order for Tracker (and, therefore, Documents) to detect your local files, they must be stored in an XDG compliant directory (such as 'Documents' or 'Music'). For more information, see Xdg user directories.

Unable to add accounts in Empathy and GNOME Online Accounts

Empathy, the engine behind integrated messaging, GNOME Online Accounts, and all other system settings based on messaging accounts will not function correctly unless the telepathy group of packages or at least one of the backends (telepathy-gabble, or telepathy-haze, for example) is installed. View descriptions of telepathy components on the telepathy wiki.

Note: Avahi daemon is required for connecting with the People Nearby account, and also in order for some desktop extensions to work correctly like Chat Status

Cannot change settings in dconf-editor

When one cannot set settings in dconf, it is possible their dconf user settings are corrupt. In this case it is best to delete the user dconf files in ~/.config/dconf/user* and set the settings in dconf-editor after.

When an extension breaks the shell

When enabling shell extensions causes GNOME breakage, you should first remove the user-theme and auto-move-windows extensions from their installation directory.

The installation directory could be one of ~/.local/share/gnome‑shell/extensions, /usr/share/gnome‑shell/extensions or /usr/local/share/gnome‑shell/extensions. Removing these two extension-containing folders may fix the breakage. Otherwise, isolate the problem extension with trial‑and‑error.

Removing or adding an extension-containing folder to the aforementioned directories removes or adds the corresponding extension to your system. Details on GNOME Shell extensions are available at the GNOME web site.

If you have trouble with uninstalling an extension via, then probably they have been installed as system-wide extensions with pacman -S gnome-shell-extensions before. Removing the package again obviously affects all user accounts.

Extensions do not work after GNOME 3 update

Note: Please bear in mind that whilst the methods below will allow you to try and activate an extension with an unsupported version of GNOME Shell, it is by no means a guarantee that the extension will work successfully. The most likely outcome of trying to activate such an extension is that GNOME Shell will crash and then restart.

Before trying the workarounds below, check if an update is available for the extension by visiting

If there is no update for your current GNOME version yet, use the following command to disable version validation for extensions:

$ gsettings set disable-extension-version-validation true

Alternatively, you could modify the extension itself, changing the supported shell version to satisfy the version validation. See the method below.

Locate the folder where your extensions are installed. It might be ~/.local/share/gnome-shell/extensions or /usr/share/gnome-shell/extensions.

Edit each occurrence of metadata.json which appears in each extension sub-folder.

Insert: "shell-version": ["3.x"]
Instead of (for example): "shell-version": ["3.4"]

"3.x" indicates the extension works with every shell version. If it breaks, you will know to change it back.

Keyboard shortcut do not work with only conky running

The GNOME shell keyboard shortcuts like Alt+F2, Alt+F1, and the media key shortcuts do not work if conky is the only program running. However, if another application like gedit is running, then the keyboard shortcuts work.

Solution: edit .conkyrc

own_window yes
own_window_transparent yes
own_window_argb_visual yes
own_window_type dock
own_window_class Conky
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager

Unable to apply stored configuration for monitors

If you encounter this message try to disable the xrandr gnome-settings-daemon plugin:

$ dconf write /org/gnome/settings-daemon/plugins/xrandr/active false

Consistent cursor theme

See Cursor themes#Desktop environments.

Windows cannot be modified with Alt-Key + mouse-button

In GNOME 3.6 and above, the mouse button modifier (the key that allows you to drag a window from a location other than the titlebar) is the Super key instead of the Alt key which was used in the past. The change was made in response to the following bug report.

To change the mouse button modifier back to the Alt key, execute the following:

$ gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier '<Alt>'  
Note: It is not possible to change this with System settings > Keyboard > Shortcuts

Slow loading of system icons/slow GDM login

Problems with the loading of system icons, such the ones in the title bar of Files, might be solved by installing (or re-installing) the gdk-pixbuf2 package.

Re-installing the aforementioned package may also fix repeated occurrences of the "Oh no! Something has gone wrong!" error screen and/or very slow loading and login with GDM as described in the following forum thread.

Artifacts when maximizing windows

Maximizing windows may cause artifacts as of GNOME 3.12.0 - see the following forum thread and bug report. A solution is detailed in the following section: #Tear-free video with Intel HD Graphics.

Tear-free video with Intel HD Graphics

Tango-edit-cut.pngThis section is being considered for removal.Tango-edit-cut.png

Reason: As of 2015-02-16, the following workaround doesn't solve tearing problems (e.g. fullscreen video) anymore when Intel TearFree option does. (Discuss in Talk:GNOME#Tear-free_video_with_Intel_HD_Graphics)

Enabling the Xorg Intel TearFree option is a known workaround for tearing problems on Intel adapters. However, the way this option acts makes it redundant with the use of a compositor (it increases memory consumption and lowers performance, see the original bug report's final comment).

As an alternative to enabling the Intel TearFree option, GNOME Shell's Mutter compositor has a tweak known to address tearing problems (see the original suggestion for this fix and its mention in the Freedesktop bug report). To enable this tweak, append the following line to /etc/environment: CLUTTER_PAINT=disable-clipped-redraws:disable-culling. Then restart the Xorg server.

Window opens behind other windows when using multiple monitors

This is possibly a bug in GNOME Shell which causes new windows to open behind others. Unchecking workspaces_only_on_primary in org/gnome/shell/overrides using dconf-editor solves this problem.

Lock button fails to re-enable touchpad

Some laptops have a touchpad lock button that disables the touchpad so that users can type without worrying about touching the touchpad. Currently, it appears that although GNOME can lock the touchpad by pressing this button, it cannot unlock it. If the touchpad gets locked you can run the following to unlock it:

$ xinput set-prop "SynPS/2 Synaptics TouchPad" "Device Enabled" 1

Passwords are not remembered

Merge-arrows-2.pngThis article or section is a candidate for merging with GNOME Keyring.Merge-arrows-2.png

Notes: please use the second argument of the template to provide more detailed indications. (Discuss in Talk:GNOME#)

If you get a password prompt every time you login, and you find that passwords are not saved, you might need to create/set a default keyring.

Ensure that the seahorse package is installed, open it ("Passwords and Keys" in system settings) and select View > By Keyring If there is no keyring in the left column (it will be marked with a lock icon), go to File > New > Password Keyring and give it a name. You will be asked to enter a password. If you do not give the keyring a password it will be unlocked automatically, even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".

GNOME Shell keyboard sources menu not visible

A menu showing the keyboard input sources (for example 'en' for an English keyboard layout) should be visible next to the status area containing icons for network, volume and power sources. If the keyboard sources menu is not visible, this is probably because you have configured your Xorg keyboard layout in a way which GNOME does not recognise.

To ensure that the menu is visible, remove any Xorg keyboard configuration you might have created and set the keyboard locale using localectl.

Upon running the command and then logging out, you should find that the keyboard input sources menu is visible in GDM and in the GNOME Shell desktop. See Input sources in GNOME for more information.

Mouse cursor missing

When using a separate window manager with gnome-settings-daemon, the mouse cursor may vanish. Run:

$ gsettings set org.gnome.settings-daemon.plugins.cursor active false

See also