GNOME/Guide/en

GNOME is a popular desktop environment capable launching Xorg and Wayland sessions. This guide Article description::attempts to describe all aspects of GNOME, including installation, configuration, and usage.

Since version 3.30, GNOME on Gentoo is able to once again run on OpenRC. See 's blog post for more detail.

The project
The GNOME project is a free software organization dedicated to the development of GNOME, a Unix/Linux desktop suite and development platform. The GNOME Foundation coordinates the development and other aspects of the GNOME Project.

The software
GNOME is a desktop environment and a development platform. This piece of free software is the desktop of choice for several industry leaders including Canonical (Ubuntu) and Red Hat (Red Hat Linux, Fedora, Centos).

The community
Like with any large free software project, GNOME has an extensive user and development base. GNOME Planet is a popular blog aggregator for GNOME hackers and contributors whereas developer.gnome.org is for the GNOME developers. GNOME Library contains a huge list of GNOME resources for end users.

Prerequisites
Historically speaking, the Xorg display server was the standard display base for all desktop environments on Linux. With GNOME 3 and beyond, a shift to the Wayland, a newer display server protocol, has begun. Systems other than NVIDIA will have no problem running GNOME sessions over Wayland.

That said, as a general fall back, it is a good idea to first read and follow the instructions in the Xorg guide to setup a X environment.

According to GNOME upstream, GNOME 3 is written with the systemd init system in mind. Because of this, it is a good idea for systemd users to read and comply with all necessary kernel settings from the systemd article.

Installation
Before installing the GNOME suite, editing the system's USE variables is a good idea. Gentoo developers provide a GNOME profile in order to aid system-wide tuning for the GNOME software stack. Select the latest stable GNOME profile before emerging GNOME.

OpenRC users using logind can select this profile:

systemd users will want to select the following profile:

Make sure that,  , and   are in the USE variable located in. It is recommended to enable support for D-Bus system-wide. systemd includes this system message bus. Add  to the USE variable as well (D-Bus is a system message bus that GNOME uses extensively). If no KDE support is required, remove  and   from USE. USE flags can be removed by adding a minus sign in front of them. See the example below for the minus sign used properly.

Once finished, begin the GNOME installation by emerging GNOME:

For a minimal GNOME installation install the package. This option provides a lightweight GNOME installation without pulling in the full GNOME desktop environment. Most users may desire to install additional packages afterward.

This will take a while, so start reading some other parts of our wiki. Done? Great, now update environment variables:

Next the remaining services and user groups will be cleaned.

Verify the  group exists. If it does, it is advisable to make each GNOME user member of that group, but step this is optional (the group is not common anymore).

Substitute  in the next command with each GNOME user's user name:

First impressions
It is time to take a look at what was just built. Either configure the session manager to run GNOME when the command is invoked (see using startx in the Xorg guide for more information), or enable the GDM service, for a more convenient way to start GNOME.

systemd
To start GDM upon boot:

To start GDM immediately, run:

Another suggestion is to activate Network Manager, in case no other network managing service is activated.

Using startx
Exit the root shell and log in as a regular user. The next step is to configure the session manager to run GNOME when the the command is invoked (see using startx in the Xorg guide for more information).

Starting with gnome-base/gnome-session-2.26.2, users will need to prepend the XDG_MENU_PREFIX variable to get the GNOME menus when using the method to start the desktop. If is not being used it will be handled automatically; no additional configuration is needed.

Now start the graphical environment by issuing :

If all goes well GNOME should happily provide a greeting. Congratulations on setting up GNOME!

Tweaking GNOME
For extra configuration options in GNOME 3 install the package. The tweak tool allows customization at a deeper level than the standard Settings frame.

Widgets in GNOME 3
By default on Gentoo GNOME 3 does not support widgets. For users who wish to obtain widget functionality a separate package is available:

After the shell extensions are installed, can be used to control defaults on a global level:

Enable click-to-install Shell Extensions through the web browser
For web browsers such as Google Chrome, Chromium, and Vivaldi be sure to get the required browser add-on through the Chrome store: https://chrome.google.com/webstore/detail/gphhapmejobijbbhgpjhcjognlahblep

Firefox users can get it here: https://addons.mozilla.org/firefox/addon/gnome-shell-integration/

Opera users will have to snag it here: https://addons.opera.com/extensions/details/gnome-shell-integration/

After the add-on has been installed for the browser of choice, a backend must also be emerged:

It should now be possible to install, manage, and uninstall shell extensions at https://extensions.gnome.org/

If things are not working as expected check the upstream installation instructions for news.

Non-root user authentication for dialogs
Certain GNOME dialogs such as Printers, adding wireless networks, and Users require administrator authentication. This is handled through and operates independently from. By default in Gentoo, the root account is the only administrator, and so even if a user account can run root commands through, authentication in these GNOME dialogs will fail.

If you would like all users of the group to be administrators, create a copy of  starting with a number lower than 50, and edit the line  to the following:

The Polkit wiki page provides more details on rules configuration.

GNOME Hotspot
In order for gnome-hotspot to work, your wireless card must support AP (access point) infrastructure mode. The following package USE flags are also needed:

In addition, the following kernel options are necessary:

Unmerge
A possible way to completely remove a GNOME installation is by explicitly uninstalling the package, then cleaning the dependencies of that package.

In order to do this sanely make sure the main ebuild repository has been synced:

Next, run a world update so that the system is fully up-to-date:

Unmerge the GNOME base package:

Finally, depclean the system:

GNOME should now be removed.

Login failure with message "Oh no something has gone wrong"
One source of this error can be the permissions for the video device. When logging in fails and a message appears that says "Oh no, something has gone wrong", then try to become a member of the group. Add the user to the video group with like so:

GNOME on Wayland session is not launching with NVIDIA
Attempting to launch GNOME on Wayland sessions is a known issue. Unfortunately the NVIDIA binary blob drivers are not presently compatible with Wayland. Systems that simply have the NVIDIA binary blob driver installed, but are not using it can see this workaround.

External resources

 * https://github.com/dantrell/gentoo-project-gnome-without-systemd - GNOME without systemd