This is a guide for upgrading since GNOME 2.32.x to GNOME 3.8.x
- 1 Introduction
- 2 Installation
- 3 Most noticeable changes for current GNOME users
- 3.1 NetworkManager will use upstream plugin to handle configs
- 3.2 Languages and encodings
- 3.3 Keyboard layouts and input methods
- 3.4 Touchpad and other input device customization
- 3.5 Configure Monitors and Displays
- 3.6 Suspend/Hibernate items in status menu
- 3.7 Suspend on laptop lid close
- 3.8 Interaction with tabs
- 3.9 Interaction with windows
- 3.10 Interaction with notifications
- 3.11 Fonts
- 3.12 Icons on the desktop
- 3.13 Logs of the session
- 4 Troubleshooting
- 4.1 Getting backtraces
- 4.2 Gnome Shell crashed/hung...
- 4.3 Unicode (i.e UTF-8) locale is needed
- 4.4 Slow Gnome Shell on NVIDIA card
- 4.5 Desktop unresponsive some seconds under heavy I/O load
- 4.6 Can't see the mouse pointer after login
- 4.7 Cannot terminate X even if I have configured xorg.conf to allow that
- 4.8 Set window theme to default value
- 4.9 GDM/Gnome not starting due 3D issues
- 5 Acknowledgements
GNOME 3 includes two desktop modes:
- Standard: this mode uses gnome-base/gnome-shell without enabled extensions and looks and behaves completely different from GNOME 2 releases. You can also enable extensions provided by gnome-extra/gnome-shell-extensions or from other packages in this mode to get the behavior you prefer. For example, some extensions provided by gnome-extra/gnome-shell-extensions will let you to have an applications menu or a places one.
- Classic: this mode uses gnome-extra/gnome-shell-extensions 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 x11-wm/compiz.
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 gnome-extra/gnome-getting-started-docs 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 gnome-extra/gnome-tweak-tool GUI, or from gsettings (can be explored using
dconf-editor, part of gnome-base/dconf) or gconf (can be explored using
gconf-editor, part of gnome-extra/gconf-editor). 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-extra/gnome-shell-extensions. 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.
eselect gnome-shell-extensions from app-admin/eselect-gnome-shell-extensions to manage system defaults that control whether extensions that were installed system-wide (i.e. in /usr/share/gnome-shell/extensions) 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
eselect gnome-shell-extensions can be overridden on a per-user basis using the extensions.gnome.org web interface, via
gnome-tweak-tool (Shell Extensions tab), or from the command line using
gsettings from dev-libs/glib. 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
desktop/gnome/systemd 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).
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
GNOME 3 requires media-sound/pulseaudio for audio support. Ensure that you have the
pulseaudio USE flag enabled globally (it will be enabled by default if you use the
desktop/gnome portage profile). For troubleshooting PulseAudio problems, see documentation on pulseaudio.org .
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.
Even if you can still login in GNOME using any other login manager, using gnome-base/gdm will give you better integration. It will be installed by gnome-base/gnome meta package and, to run it at startup, you can enable the service as follows:
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:
|<dev-lang/vala:0.20||dev-lang/vala:0.20|| New enough versions of portage will resolve the dependency blocker automatically but, if you hit blocking issue due this, running |
|gnome-base/gnome-applets||None of GNOME 2 applets can be used in GNOME 3. Some traditional applet functionality can be replicated using third-party GNOME Shell extensions.|
Installing Gnome 3.8
You should use gnome-base/gnome if possible to ensure you get a better experience. If you were running gnome-base/gnome-light 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)
Most noticeable changes for current GNOME users
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 sys-apps/accountsservice. 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
jrandom use British English, you can (as root) edit /var/lib/AccountsService/users/jrandom 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 xorg.conf keyboard layout settings. Instead, keyboard layouts and input methods are configured via
ibus which is integrated into GNOME Shell.
To add a keyboard layout, open System Settings (or gnome-control-center 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 gnome-base/gnome-settings-daemon with the
short-touchpad-timeout 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 input-device.sh 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
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
Alt 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 gnome-extra/gnome-shell-extensions and run
to enable the extension for all users by default, or use
gnome-tweak-tool (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
gnome-tweak-tool GUI (Shell tab), or by using
gsettings 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 gnome-extra/office-runner, 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 app-editors/gedit, gnome-base/nautilus and www-client/epiphany. 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
Alt + Middle click, GNOME 3.6 replaced the
Alt key with the
Super (Windows Logo) key. If you wish to change back to the old behavior, this can be done using
gnome-tweak-tool (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
<Super> 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  . 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 gnome-extra/gnome-shell-extensions-topicons and, once you install that package, enable it as usual, for example:
GNOME 3 uses media-fonts/cantarell 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 media-fonts/dejavu. This can be done using
gnome-tweak-tool (Fonts tab), or you can set DejaVu (size 10) as the default font from the terminal:
Icons on the desktop
In GNOME 3, ~/Desktop 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
gnome-tweak-tool GUI (Desktop tab), or use the
gsettings 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 ~/.xsession-errors or ~/.cache/gdm/session.log, they are now directly logged by journald and, then, you will need to run
journalctl to see them (see
man journalctl for learning more about its usage).
At first you need to review Gentoo documentation for ensuring affected packages are built with debugging symbols. After that, you need to install app-admin/abrt 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
gnome-shell you can press
Alt + F2 type
r and press
ENTER. If it doesn't work, you can try to switch to a console and run
killall -9 gnome-shell. If still no luck, you can restart X completely running (in the case of gdm):
Unicode (i.e UTF-8) locale is needed
Slow Gnome Shell on NVIDIA card
Sometimes people change nvidia settings using media-video/nvidia-settings, 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 x11-misc/lightdm-gtk-greeter as it doesn't need 3D support or re-emerge gnome-base/gdm 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.
We would like to thank the following authors and editors for their contributions to this guide: