From Gentoo Wiki
Jump to: navigation, search

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:

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: yelp /usr/share/help/C/gnome-help/

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 web interface; there are also numerous developers publishing extensions on various third-party websites, which come with their own installation instructions.

Gentoo uses 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:

root #eselect gnome-shell-extensions list -v

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

root #eselect gnome-shell-extensions enable

Defaults managed by eselect gnome-shell-extensions can be overridden on a per-user basis using the 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

user $gsettings set enabled-extensions '["", "", ""]'

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

The code quality of extensions is highly variable. Some extensions contain memory leaks and others can render GNOME completely unusable. Gentoo cannot offer support for problems caused by third-party extensions.


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).

You can use
root #eselect profile list
to see the available profiles and
root #eselect profile set default/linux/amd64/13.0/desktop/gnome/systemd
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:

FILE /etc/portage/package.use Sync USE flags between packages
sys-apps/systemd gudev introspection keymap 
sys-fs/eudev gudev hwdb introspection keymap 
>=sys-fs/udev-171 gudev hwdb introspection keymap 
>=virtual/udev-171 gudev hwdb introspection keymap

And many other changes

Required software


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 .


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.

Recommended software


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:

root #systemctl enable gdm

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:

Old Replacement Observations
<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 emerge -1 vala:0.20 should solve it
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.
gnome-extra/bug-buddy app-admin/abrt
gnome-extra/evolution-exchange gnome-extra/evolution-ews

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 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:

root #emerge --deselect gnome-light

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

root #emerge --deselect gnome-utils --deselect gnome-applets --deselect seahorse-plugins --deselect gnome-games --deselect gnome-pilot --deselect dev-cpp/libpanelappletmm --deselect gnome-extra/deskbar-applet --deselect gnome-extra/fast-user-switch-applet --deselect gnome-extra/file-browser-applet --deselect gnome-extra/gnome-hdaps-applet --deselect gnome-extra/gnome-swallow --deselect gnome-extra/libgail-gnome --deselect gnome-extra/lock-keys-applet --deselect media-gfx/byzanz --deselect net-analyzer/gnome-netstatus --deselect net-analyzer/netspeed_applet --deselect x11-misc/glunarclock --deselect gcalctool

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

And, finally, upgrade:

root #emerge -avuDN --keep-going @world gnome-base/gnome

(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:

FILE /var/lib/AccountsService/users/jrandom Simple example of an AccountsService user file

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:

user $cp /usr/share/gnome-settings-daemon-3.0/ ~/
user $chmod +x ~/
user $gsettings set org.gnome.settings-daemon.peripherals.input-devices hotplug-command ~/

and create the following file:

# If the device is a touchpad ...
if [[ -z "${device#*TouchPad*}" ]]; 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
# All further processing will be disabled if $retval == 0
exit $retval
If the custom hotplug command does not terminate with exit value 0, gnome-settings-daemon will set its own settings on the input device, likely clobbering the settings that the hotplug command had changed.

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:

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

Configure Monitors and Displays

GNOME 3.8 uses xrandr to setup the monitors.

Try to configure your displays with
user $gnome-control-center display

To apply the settings as a system-wide default, copy ~/.config/monitors.xml to /etc/gnome-settings-daemon/xrandr/monitors.xml.

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 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

root #eselect gnome-shell-extensions enable '

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 need to change one parameter in /etc/systemd/logind.conf:

FILE /etc/systemd/logind.conf Disable suspend on laptop lid close

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:

user $gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier '<Alt>'

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 [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 gnome-extra/gnome-shell-extensions-topicons and, once you install that package, enable it as usual, for example:

root #eselect gnome-shell-extensions enable


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:

user $gsettings set org.gnome.desktop.interface font-name 'DejaVu Sans 10'
user $gsettings set org.gnome.desktop.interface document-font-name 'DejaVu Sans 10'
user $gconftool-2 -s -t string /apps/metacity/general/titlebar_font 'DejaVu Sans Bold 10'

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:

user $gsettings set org.gnome.desktop.background show-desktop-icons true

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).


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 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):

root #systemctl restart gdm

Unicode (i.e UTF-8) locale is needed

As reported in bug #481168 (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 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 ~/.nvidia-settings-rc.

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.

Also setting "fs.inotify.max_user_watches=100000" in sysctl.conf can help as reported in upstream bug#712311 and Fedora bug#1069299. Please read /etc/sysctl.d/README for learning about how to handle sysctl.conf settings.

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:

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

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:

user $gsettings reset org.gnome.desktop.wm.preferences theme

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:

user $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:

user $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.

You need media-libs/mesa[llvm] for software rendering.

This article is based on a document formerly found on our main website
The following people have contributed to the original document: eva, pacho, tetromino
They are listed here as the Wiki history does not provide for any attribution. If you edit the Wiki article, please do not add yourself here, your contributions are recorded on the history page.