Project:GNOME/GNOME3 upgrade guide

This is a guide for upgrading from GNOME 2.32.x or 3.6.x to GNOME 3.8.x

General changes
Please see the GNOME 3.8 Release Notes for what is new in this major release of GNOME.

Current users of GNOME 2 would also want to glance at the release notes for 3.0, 3.2 , 3.4 , and 3.6. Briefly: GNOME 3 includes two desktop modes: standard and classic. Fallback mode uses  to get a similar appearance and behavior to GNOME 2. Standard mode uses  without enabled extensions and looks and behaves completely differently from GNOME 2 releases (anyway, you can also enable extensions provided by   or others in this mode to get the behavior you prefer). The choice of desktop mode is done choosing desired session in login screen, and both need 3D graphics capabilities, otherwise a fallback mode relying on software rendering will be used.

There is a quick tour of standard mode's GNOME Shell available on the GNOME website. For an in-depth guide to using GNOME Shell, see the GNOME Shell cheat sheet. You can also open docs provided by  to see more documentation about new Gnome Shell experience (i.e:.

GNOME Shell at first may feel alien and limited to an experienced GNOME 2 user. We strongly encourage users to persist and make themselves use it for a few days; those who take the time to get used to GNOME Shell's behavior usually grow to love it and don't want to go back to a GNOME 2-like desktop environment.

Keyboard layouts and input methods
GNOME 3.6 does not use traditional  keyboard layout settings. Instead, keyboard layouts and input methods are configured via  which is integrated into GNOME Shell.

To add a keyboard layout, open System Settings (or from the terminal) and go to Region & Language → Input Sources.

Unfortunately, in GNOME 3.6 the System Settings GUI does not allow setting the usual shortcuts (e.g.  ) for switching keyboard layouts. Users who use multiple keyboard layouts and need to switch between them from the keyboard will need to use  and select their desired shortcut from the Typing → Modifiers-only input sources switcher shortcut menu. Alternatively, from a terminal:

Use left Alt Shift to switch between keyboard layouts

Suspend menu item
GNOME Shell 3.6 (unlike earlier GNOME 3 releases) always shows a Power Off menu item by default in the upper-right corner menu. However (unlike earlier GNOME releases) it now no longer shows a Suspend menu item by default. The Suspend menu item becomes visible after clicking on the upper right corner menu and holding down the  key. Laptops can also be suspended simply by shutting the lid.

If you need an easily discoverable GUI for suspending the machine, you can install the alternative-status-menu extension. To do so, emerge  and run

Enabling the alternative-status-menu extension

to enable the extension for all users by default, or use  ( Shell Extensions tab) to enable it on a per-user basis.

Evolution 3.6 plugins
Current versions of  and   are incompatible with Evolution 3.6, and you will need to uninstall them before upgrading to GNOME 3.6. Users of  should try switching to   as   development is abandonned.

Interaction with tabs
Since Gnome 3.0, some applications stopped switching tabs when scolling over them. This is behavior is intended by upstream actually covers at least ,   and. This behavior will not be patched by Gentoo Gnome team so if you find it annoying, please report directly at Gnome bugzilla.

Interaction with windows
If you were used to move and resize windows using , Gnome 3.6 replaced the   key with the   (Windows Logo) key. If you wish to change back to the old behavior, this can be done using  ( Windows tab), or from the terminal:

set Alt as modifier key for window interaction

Logs of the session
If you were used to find the logs of the current session in , the file has now moved to XDG compliant location:.

Languages and encodings
GNOME 3 obtains user language settings from. The language can be set in GNOME from the My Account entry in the upper right corner menu. Alternatively, you can directly edit AccountsService user files. For example, to have user  use British English, you can (as root) edit  so it reads the following:

Simple example of an AccountsService user file

Fonts
GNOME 3 uses  as its default font. Unfortunately, Cantarell currently only includes a subset of Latin and Cyrillic characters. Users of languages with alphabetic writing systems which are not yet covered by Cantarell will probably want to switch to another font, such as. This can be done using  ( Fonts tab), or from the terminal:

Set DejaVu (size 10) as the default font

Applets
GNOME 2 applets cannot be used in GNOME 3. Fallback mode allows applets, although some have not yet been ported to the new, gtk3-based APIs. In standard mode, there are no applets at all. Some traditional applet functionality can be replicated using third-party GNOME Shell extensions.

In order to manage fallback gnome-panel settings (either add/remove or rearrange applet positions) one has to hold down the  key when clicking on the panel. This opens relevant menu for changing either panel or applet settings.

Suspend on laptop lid close
GNOME 3 will, by default, suspend a laptop when the lid is closed. If you do not like this behavior, you can change it via the  GUI ( Shell tab), or using   from the terminal:

Only turn off the screen when laptop lid is closed on AC power

One of the most common reasons for not wanting to suspend on laptop lid close is to carry a laptop to another room without losing the network connection. To do so, you can install , which allows temporarily inhibiting GNOME's suspend-on-lid-close behavior for up to 10 minutes.

Icons on the desktop
In GNOME 3, Nautilus by default no longer manages the desktop, and the folder is simply treated as a normal folder with files.

If you want to have Nautilus manage the desktop like in GNOME 2, you can change the corresponding setting in the  GUI ( Desktop tab), or use the   command from the terminal:

Making Nautilus manage the desktop

Compiz
GNOME 3 standard mode (i.e. GNOME Shell) is incompatible with Compiz.

PulseAudio
GNOME 3 requires  for audio support. Ensure that you have the  USE flag enabled globally (it will be enabled by default if you use the   portage profile). For troubleshooting PulseAudio problems, see documentation on pulseaudio.org.

Touchpad and other input device customization
In GNOME 3.6, if you have "disable touchpad while typing" selected, the touchpad will be disabled for 1 second after a keyboard key is pressed. In GNOME 2, this interval was 500 milliseconds. If you like to disable the touchpad while typing, but prefer the shorter timeout interval like in GNOME 2, you can emerge  with the   USE flag enabled.

GNOME 3 allows setting a custom command for advanced customization of input device settings. For example, suppose that you want to configure your touchpad to enable two-finger scrolling (both vertical and horizontal) and edge scrolling (vertical only). You could do

Setting a new GNOME input device hotplug script

and edit so it ends as follows:

if -z "${device; then	# ... enable two-finger scrolling (vertical and horizontal) ...	xinput set-prop "${device}" "Synaptics Two-Finger Scrolling" 1 1	# ... and edge scrolling (vertical only, no horizontal, no coasting) ...	xinput set-prop "${device}" "Synaptics Edge Scrolling" 1 0 0 fi exit $retval
 * 1) If the device is a touchpad ...
 * 1) All further processing will be disabled if $retval == 0

If, for whatever reason, you want to completely prevent GNOME 3 from automatically modifying your mouse and touchpad settings (note that this will also prevent custom input hotplug commands, such as above, from modifying mice and touchpads!), you can run the following:

Prevent GNOME from managing the mouse and touchpad

General configurability and extensions
GNOME 3 is designed to appear significantly less configurable than GNOME 2. For example, by default there is no easily discoverable GUI for changing the Gtk+ theme. Many configuration settings are hidden, but can still be changed using the  GUI, or from gsettings (can be explored using  , part of   ) or gconf (can be explored using   ). Discussion of most of these settings is outside the scope of this guide.

GNOME Shell's behavior can be significantly altered using extensions. Gentoo packages the extensions from the official GNOME repository as. GNOME Shell comes with a browser plugin that allows users to install extensions from the https://extensions.gnome.org/ web interface; there are also numerous developers publishing extensions on various third-party websites.

Gentoo uses  to manage system defaults that control whether extensions that were installed systemwide (i.e. in  ) should be enabled. Newly-installed systemwide extensions start out disabled by default.

Enabling alternative status menu and dock extensions by default for all users

Defaults managed by  can be overridden on a per-user basis using the extensions.gnome.org web interface, via   ( Shell Extensions tab), or from the command line using. For example, to load the alternative status menu and dock extensions, and disabling all other extensions, a user can run

Enabling alternative status menu and dock extensions (and disabling all others!) for the current user

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * tetromino
 * eva