GNOME/Guide

This page contains changes which are not marked for translation.

Other languages:

Resources

GNOME is a popular desktop environment capable launching Xorg and Wayland sessions. This guide 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.^[1] See GNOME without systemd for more detail.

What is GNOME?

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 Enterprise Linux, Fedora, CentOS Stream).

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

USE Flags

USE flags for gnome-base/gnome Meta package for GNOME, merge this package to install

`+bluetooth`	Enable Bluetooth Support
`+classic`	Install gnome-extra/gnome-shell-extensions for the Gnome Shell Classic mode
`+extras`	Install additional GNOME applications
`accessibility`	Add support for accessibility (eg 'at-spi' library)
`cups`	Add support for CUPS (Common Unix Printing System)

Data provided by the Gentoo Package Database · Last update: 2024-05-06 07:08 More information about USE flags

Profile

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

Important
Read relevant documentation before performing any profile changes.

OpenRC

OpenRC users using logind can select the GNOME OpenRC profile:

root #eselect profile set default/linux/amd64/23.0/desktop/gnome

systemd

Warning
Read the systemd documentation before changing to a systemd profile.

systemd users will want to select the following profile:

root #eselect profile set default/linux/amd64/23.0/desktop/gnome/systemd

Make sure that X, gtk, and gnome are in the USE variable located in /etc/portage/make.conf. It is recommended to enable support for D-Bus system-wide. systemd includes this system message bus.

FILE /etc/portage/make.confExample global USE flags for a GNOME desktop environment

USE="-kde X gtk gnome systemd"

Note
When using the desktop/gnome/systemd profile, these USE flags will be set automatically. It is possible to check the system profile by running eselect profile list. Modifications can be made by running eselect profile set <profile-name> as root. Be sure to replace "<profile-name>" with the number or name of the desired profile.

Combined hardened profiles

Users that run hardened profiles can also combine it with all the features of the GNOME desktop profile. For steps on doing this please follow GNOME/Guide/Hardened_GNOME_Profiles.

Emerge

Tip
Speed up compiling times by removing net-libs/webkit-gtk as a dependency.

Once finished, begin the GNOME installation by emerging the GNOME desktop suite:

root #emerge --ask gnome-base/gnome

Note
Some users may desire to keep their installation light and only install additional packages in an on-demand manner. This is helpful on systems with limited disk space. For this reason a minimal GNOME option exists as the gnome-base/gnome-light package. This option installs the essentials of the GNOME desktop environment suite:

root #emerge --ask gnome-base/gnome-light

Also, consider disabling previewer for gnome-base/nautilus along with removing GNOME online accounts on low end devices to avoid net-libs/webkit-gtk and reduce build time:

FILE /etc/portage/package.use/nautilusDisabling previewer for nautilus

gnome-base/nautilus -previewer

Note
Portage may run into a circular dependency error when emerging libpulse. If this happens, emerge the libsndfile dependency with the minimal useflag before emerging GNOME:

root #USE="minimal" emerge --ask --oneshot libsndfile

This will take a while. Once it’s done, update environment variables:

root #env-update && source /etc/profile

Next the remaining services and user groups will be cleaned.

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

root #getent group plugdev

plugdev:x:104:

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

root #gpasswd -a <username> plugdev

First impressions

It is time to take a look at what was just built. Either configure the session manager to run GNOME when the startx 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.

Enabling GDM

Note
Help on troubleshooting issues with GDM can be found in the GNOME/GDM article.

OpenRC

For OpenRC systems, elogind is a dependency of GDM and must be started for GDM to run properly:

root #

rc-update add elogind boot

root #

rc-service elogind start

Next add display-manager-init to the default runlevel and start the service:

root #emerge --ask --noreplace gui-libs/display-manager-init

In /etc/conf.d/display-manager set DISPLAYMANAGER to "gdm"

FILE /etc/conf.d/display-manager

DISPLAYMANAGER="gdm"

To start on boot, add display-manager to the default runlevel:

root #

rc-update add display-manager default

To start GDM either reboot or start it immediately:

root #

rc-service display-manager start

systemd

To start GDM upon boot:

root #systemctl enable gdm.service

To start GDM immediately, run:

root #systemctl start gdm.service

Tip
The following command both enables and starts GDM immediately:

root #systemctl enable --now gdm.service

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 startx command is invoked (see using startx in the Xorg guide for more information).

user $echo "exec gnome-session" > ~/.xinitrc

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 ~/.xinitrc method to start the desktop. If ~/.xinitrc is not being used it will be handled automatically; no additional configuration is needed.

user $sed -i '1i\export XDG_MENU_PREFIX=gnome-' ~/.xinitrc

Now start the graphical environment by issuing startx:

user $startx

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

Privacy

Removing GNOME online accounts in the control center

Some users might be concerned about the fact that there is an online accounts section is the GNOME control center, which enables the user to connect the system to various services like Google, Microsoft, etc. In Portage, a USE flag can be set to remove this functionality:

FILE /etc/portage/make.conf

USE="... -gnome-online-accounts"

This will tell Portage to not install the net-libs/gnome-online-accounts package if possible.

Re-emerge world with the --changed-use flag and clean unused dependencies.

root #emerge --ask --changed-use --update --deep @world

root #emerge --depclean

Note
Because of gnome-extra/gnome-contacts package being part of gnome-base/gnome via gnome-base/gnome-core-apps, the -gnome-online-accounts USE cannot be set as gnome-extra/gnome-contacts makes this a hard requirement to be enabled. gnome-base/gnome-light is an alternative though several other packages may be required for a full experience.

Configuration

Mixed localization

It could be general to have C as the global default locale, with a different one for the desktop. This can be achieved by add settings:

FILE ~/.config/environment.d/01_localize.confOverride locale for user session

LANG="zh_CN.utf8"
LC_MESSAGES="zh_CN.utf8"
LC_TIME="zh_CN.utf8"

Then choose the region for locale in gnome-setting-center, or via command:

user $gsettings set org.gnome.system.locale region 'zh_CN.utf8'

Note
With global locale default to C, only set the region is not likely to change the locale for desktop, for which, configuration in environment.d is necessary, especially the LC_MESSAGES variable. And to make it work for sure, the following packages may be necessary: ≥ sys-apps/systemd-249.6-r1 and ≥ gnome-base/gnome-40.0.

Log out, make sure the old session is killed and re-login, these settings will be applied to the new session.

To override session's locale for terminal in gnome, add:

FILE ~/.bashrcOverride locale for terminal

LANG="C.utf8"
LC_MESSAGES="C.utf8" 
LC_TIME="C.utf8"

Tweaking GNOME

For extra configuration options in GNOME 40 install the gnome-extra/gnome-tweaks package. The tweak tool allows customization at a deeper level than the standard settings application.

Advanced tweaking

Advanced tweaking for GNOME can be performed from the command line via the gsettings or dconf commands or graphically via dconf-editor. All modifiable settings are accessible using these tools. For more information, see upstream's documentation.

Widgets in GNOME 40

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

root #emerge --ask gnome-extra/gnome-shell-extensions

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

root #eselect gnome-shell-extensions list

Available extensions (* means enabled for all users by default):
  [1]   alternate-tab@gnome-shell-extensions.gcampax.github.com
  [2]   apps-menu@gnome-shell-extensions.gcampax.github.com
  [3]   auto-move-windows@gnome-shell-extensions.gcampax.github.com
  [4]   drive-menu@gnome-shell-extensions.gcampax.github.com
  [5]   launch-new-instance@gnome-shell-extensions.gcampax.github.com
  [6]   native-window-placement@gnome-shell-extensions.gcampax.github.com
  [7]   places-menu@gnome-shell-extensions.gcampax.github.com
  [8]   screenshot-window-sizer@gnome-shell-extensions.gcampax.github.com
  [9]   user-theme@gnome-shell-extensions.gcampax.github.com
  [10]  window-list@gnome-shell-extensions.gcampax.github.com
  [11]  windowsNavigator@gnome-shell-extensions.gcampax.github.com
  [12]  workspace-indicator@gnome-shell-extensions.gcampax.github.com

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:

root #emerge --ask gnome-extra/gnome-browser-connector

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 sys-auth/polkit and operates independently from app-admin/sudo. By default in Gentoo, the root account is the only administrator, and so even if a user account can run root commands through sudo, authentication in these GNOME dialogs will fail.

To make all users of the wheel group administrators, create a copy of /usr/share/polkit-1/rules.d/50-default.rules starting with a number lower than 50, and edit the line return ["unix-user:0"] to the following:

FILE /etc/polkit-1/rules.d/49-wheel.rulesAdministrator wheel group

polkit.addAdminRule(function(action, subject) {
    return ["unix-group:wheel"];
});

The Polkit page provides more details on rules configuration.

GNOME hotspot

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

FILE /etc/portage/package.useConnection Sharing and Access Point Support

net-misc/networkmanager connection-sharing
net-wireless/wpa_supplicant ap

In addition, the following kernel options are necessary:

KERNEL NAT options (locations for kernel 4.14)

Networking support (NET [=y])
    Networking options --->
        Network packet filtering framework (Netfilter) (NETFILTER [=y]) --->
            IP: Netfilter Configuration --->
                <*/M> IPv4 NAT (CONFIG_NF_NAT_IPv4)
                <*/M> IPv4 masquerade support
                <*/M> IP tables support (required for filtering/masq/NAT) (IP_NF_IPTABLES [=y])
                <*/M> iptables NAT support

Removal

Unmerge

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

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

root #emerge --sync

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

root #emerge --ask --update --newuse --deep --with-bdeps=y @world

Unmerge the GNOME base package. Substitute the base package with gnome-base/gnome-light if the 'light' version of the package was installed instead:

root #emerge --ask --depclean gnome-base/gnome

Finally, depclean the system:

root #emerge --ask --depclean

GNOME should now be removed.

Troubleshooting

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 video group. Add the user to the video group with gpasswd like so:

root #gpasswd -a <user> video

GNOME on Wayland session is not launching with NVIDIA

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

For at least gnome-base/gdm-44.1 it is required to set NVreg_PreserveVideoMemoryAllocations=1 in /etc/modprobe.d/nvidia.conf, otherwise Wayland support is being disabled.

GNOME built-in screen recorder is not working

GNOME's screen recorder uses vp8 codec which is developed by Google. The recorder needs this codec and pipewire screencast feature to record the desktop. It can be enabled it via the the vpx and screencast USE flags in either the make.conf or package.use files.

FILE /etc/portage/make.conf

USE="vpx screencast"

GNOME and Pinentry not working with GPG

For example when using Evolution to sign emails with PGP, the private key needs to be decrypted. If this key has a password, a Pinentry dialogue trys to open. To enable the Gtk version, these configuration files need to be edited.

FILE ~/.gnupg/gpg.conf

use-agent
pinentry-mode loopback

FILE ~/.gnupg/gpg-agent.conf

pinentry-program /usr/bin/pinentry-gnome3

Nautilus is not showing thumbnails for .mp4 video files

The ffmpeg USE flag is not enabled globally in default desktop/gnome profile. Enable it locally for the media-plugins/gst-plugins-meta:

FILE /etc/portage/package.use

media-plugins/gst-plugins-meta ffmpeg

Emerge @world with --changed-use (-U) flag:

root #emerge --changed-use @world

The good idea is to delete .cache/thumbnails in your $HOME folder:

user $rm -r ~/.cache/thumbnails

External resources

https://github.com/dantrell/gentoo-project-gnome-without-systemd - GNOME without systemd.
https://github.com/bdaase/remove-alt-tab-delay - Remove the 0.15 second Alt+Tab delay.
https://help.gnome.org/admin/ - Upstream GNOME administrator guide.
https://help.gnome.org/users/ - Upstream GNOME user guide.

References

↑ https://www.gentoo.org/news/2019/03/27/gnome-330-openrc.html

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Lars Strojny,
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.

[1] ttps://www.gentoo.org/news/2019/03/27/gnome-330-openrc.html

[1]