Project:GNOME/GNOME3 upgrade guide

This is a guide for upgrading since GNOME 2.32.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 will also want to take a glance at the release notes for 3.0, 3.2, 3.4 and 3.6.

GNOME 3 includes two desktop modes:
 * Standard: this mode uses without enabled extensions and looks and behaves completely different from GNOME 2 releases. You can also enable extensions provided by  or from other packages in this mode to get the behavior you prefer. For example, some extensions provided by  will let you to have an applications menu or a places one.
 * Classic: this mode uses to get a similar appearance and behavior to GNOME 2.

The choice of desktop mode is done by choosing the desired session at the login screen, and both modes need 3D graphics capabilities, otherwise a fallback mode relying on software rendering will be used. Both modes are incompatible with.

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 the documentation provided by to see more documentation about the new GNOME Shell experience (i.e:  ).

GNOME Shell at first may feel alienating and limiting to an experienced GNOME 2 user. We strongly encourage users to persist and use it for a few days; those who take the time to get used to GNOME Shell's behavior usually will love it and don't want to go back to a GNOME 2-like desktop environment, if you still doesn't like it, you can try to enable some of the available extensions while running Standard mode before finally switching to Classic one.

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  , part of ). 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, which come with their own installation instructions.

Gentoo uses  from  to manage system defaults that control whether extensions that were installed system-wide (i.e. in ) should be enabled. Run the following to list all installed extensions and their descriptions:

Newly-installed system-wide extensions start out disabled by default and can be enabled by default for all users using

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   from. For example, to load altermative-status, apps-menu and window-list extensions, and disabling all other extensions, a user can run

to enable alternative-status, apps-menu and window-list extensions (and disabling all others!) for the current user.

Using gnome/systemd subprofile
People are highly encouraged to switch to the   subprofile as it includes settings that will make the update easier (as it sets proper defaults for USE flags and masking to prevent dependency blockers and therefore provides a better desktop experience).

You can use to see the available profiles and  for setting the proper profile.

If you still refuse to use gnome subprofile you will need to ensure you maintain certain USE flags enabled in sync to prevent ugly dependency blocker issues:

And many other changes

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.

Systemd
GNOME 3.8 requires systemd to be running to get it working properly, otherwise, you will get broken power management and multiseat handling, and also some more problems because upstream has moved away from the obsolete consolekit to logind (that needs systemd to be running to work).

You must follow the systemd guide to migrate from openRC+udev to it. Systemd will be needed while running GNOME, then, you can simply prepare your kernel and system as the guide suggest and, then, upgrade all your system on a run with commands listed below. That way, you will end up with Gnome 3.8 and systemd installed and will be able to reboot once all is configured as systemd guide says.

3D support
GNOME 3 relies on proper 3D support, please ensure you have a working 3D setup in your machine and refer to Troubleshooting to know how to try to solve some problems.

GDM
Even if you can still login in GNOME using any other login manager, using will give you better integration. It will be installed by meta package and, to run it at startup, you can enable the service as follows:

Obsolete software
The following packages are no longer needed or are replaced by others. Portage will take care of migrating most of them automatically in most cases, but, depending on the packages listed in your world file and other setups customizations, manual intervention is needed to remove old entries:

Installing Gnome 3.8
At first, please look at systemd guide to ensure systemd pre-installation configuration steps are done before running following commands to update to Gnome 3.8 and systemd.

You should use if possible to ensure you get a better experience. If you were running and want to migrate away to the other meta you can run the following before updating your system:

You will need to also run the following to avoid blockers with packages relying on old stuff:

Additionally, you could need to disable "gnome" USE for app-dicts/verbiste, app-i18n/im-ja, dev-ml/lablgtk.

And, finally, upgrade:

(You can try to specify, for example, a higher backtracking value appending something like --backtrack=100 to try to avoid blockers)

After that, please remember you read elog messages logged by updated ebuilds (usually in /var/log/portage/elog/summary.log, depending on your portage configuration) and continue with systemd Post-installation configuration steps.

It's also required to take a look to the below section to not get unwanted surprises (like losing network due changes in the way NetworkManager is configured)

NetworkManager will use upstream plugin to handle configs
When running Systemd, NetworkManager will use upstream plugin to handle configs (called 'keyfile'), then, you probably will need to reconfigure your network settings. If you have problems with this migration (like NetworkManager failing to start), you need to verify that old 'ifnet' plugin is not referred from /etc/NetworkManager/NetworkManager.conf

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:

But, normally, you won't need to change this if wanting to use the same language as the used system wide.

Keyboard layouts and input methods
GNOME 3.8 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. That dialog will also tell you how to change keyboard layout to switch between multiple keyboard layouts.

Touchpad and other input device customization
Apart of the settings you can change in "Control Center -> Mouse", if you have "disable touchpad while typing" selected in "Control Center -> Mouse", 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 set a new GNOME input device hotplug script using the terminal:

and create the following file:

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:

Configure Monitors and Displays
GNOME 3.8 uses xrandr to setup the monitors.

Try to configure your displays with

To apply the settings as a system-wide default, copy  to

Suspend/Hibernate items in status menu
GNOME Shell 3.8 always shows a Power Off menu item by default in the upper-right corner menu. 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.

To change status menu default items, you should probably try the alternative-status-menu extension. To do so, emerge and run

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

This will offer you separated "Suspend" and "Hibernate" menu items.

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 by using   you can only turn off the screen when laptop lid is closed on AC power from the terminal:

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.

Interaction with tabs
Since GNOME 3.0, some applications stopped switching tabs when scrolling over them. This intended behavior by upstream actually covers at least, and. This behavior will not be patched by the Gentoo GNOME team so if you find it annoying, please report it directly at the 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 you can use the terminal to set Alt as modifier key for window interaction:

Interaction with notifications
For GNOME 3.8 this action has been updated to react to the force with which the pointer is pressed against the screen edge. Only a determined push will cause the Message Tray to open. This enhancement avoids accidental triggers and is quicker and more immediate. To open the tray usually moving mouse to the button and, either trying to move it even more down or sticking it there will work. You can also open the tray pressing  key or clicking on notification shown when a new one arrives in Activities overview.

Also, notifications handling has changed a lot during GNOME 3 cycles [1 ] [2 ]. Since some commonly used applications are still not using notifications in this way, they can be hard to use. To let this applications behave more similar to GNOME 2 you can use and, once you install that package, enable it as usual, for example:

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 you can set DejaVu (size 10) as the default font from the terminal:

Icons on the desktop
In GNOME 3, folder is simply treated as a normal folder with files instead of its contents being shown in the GNOME desktop. If you want to manage your desktop files like in GNOME 2, you can change the corresponding setting in the  GUI (Desktop tab), or use the   command from the terminal to make Nautilus manage the desktop:

This change is not needed if you are using GNOME Classical mode.

Currently, it's not possible to create launchers in desktop (see upstream bug #702587), as a workaround, you can try to copy existing launchers from /usr/share/applications to your ~/Desktop.

Logs of the session
If you were used to finding the logs of the current session in or, they are now directly logged by journald and, then, you will need to run   to see them (see   for learning more about its usage).

Getting backtraces
At first you need to review Gentoo documentation for ensuring affected packages are built with debugging symbols. After that, you need to install and enable its provided unit files to be run at boot time.

Gnome Shell crashed/hung...
Sometimes something fails and you can see GNOME hangs or crashes, for restarting  you can press   type   and press. If it doesn't work, you can try to switch to a console and run. If still no luck, you can restart X completely running (in the case of gdm):

Unicode (i.e UTF-8) locale is needed
As reported in (upstream bug#698952), you need to use a UTF-8 locale or, otherwise, you will hit a lot of crashes.

Slow Gnome Shell on NVIDIA card
Sometimes people change nvidia settings using, this can lead to performace or other problems. Before reporting a issue, you should try to remove your changed settings to use defaults again. Settings are placed at

Desktop unresponsive some seconds under heavy I/O load
Sometimes, under heavy I/O load (like while emerging or copying files), you could experience some stalls for a few seconds. You should consider using different IO Schedulers in your kernel and stick with the one performing better for you. Currently three are offered: cfq, deadline and bfq.

Can't see the mouse pointer after login
As reported in upstream bug#694758, some people can see their mouse pointer is invisible for some time just after login in on a fresh reboot. Until a proper fix is found, you can disable cursor gnome-settings-daemon plugin to workaround this:

This will prevent the mouse pointer to become invisible and not come back even not running a touchscreen.

Cannot terminate X even if I have configured xorg.conf to allow that
Gnome honors XKB options set on xorg.conf.d files if the user doesn't have any configuration yet, i.e. for new user accounts. Otherwise previous users configuration is respected. But please take care Gnome will read configurations files from /etc/X11/xorg.conf.d/, not from old style /etc/X11/xorg.conf file.

Set window theme to default value
In some cases the old metacity window manager theme is migrated and inherited in Gnome Shell. To reset its value to default value you will need to run:

GDM/Gnome not starting due 3D issues
If you are having 3D problems related with corrupted images, you could have hit a Xorg driver bug. You need to report a bug for that downstream on Gentoo.

Then, you can additionally add your card to the blacklist to force the usage of software rendering. The file you need to change is /usr/share/gnome-session/hardware-compatibility, and the line you need to append (preceded by a "-") can be obtained running: glxinfo | grep renderer

If you keep having problems, you should check software rendering is ok. To this end, you could need to temporally use as it doesn't need 3D support or re-emerge  with USE="-gnome-shell fallback", and run, from a desktop or window manager not relying on 3D: LIBGL_ALWAYS_SOFTWARE=1 LIBGL_DEBUG=verbose glxinfo | grep render

that will likely show you errors loading swrast that could guide us to solve the problem.

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


 * eva
 * pacho
 * tetromino