GNOME

GNOME (/(ɡ)noʊm/) is a desktop environment for both Wayland and Xorg that seeks to be "an independent computing platform for everyone."

This article is an extension of the documentation in the NixOS manual.

Installation

To use GNOME on NixOS, the following configuration options must be set:

❄︎ /etc/nixos/configuration.nix

{
  # Pre 25.11
  services.xserver.enable = true;
  services.xserver.displayManager.gdm.enable = true;
  services.xserver.desktopManager.gnome.enable = true;

  # As of 25.11
  services.displayManager.gdm.enable = true;
  services.desktopManager.gnome.enable = true;
}

Despite the options in NixOS versions before 25.11 being under the xserver namespace, GNOME runs offers Wayland by default. 25.11 and later versions remove support for the Xorg session entirely (though Xwayland is still included and supported for compatibility).

GNOME Extensions

GNOME offers support for changing/overhauling the user interface (GNOME Shell) through the use of Extensions. Extensions are bundles of third-party GJS modules that are loaded while GNOME is running to augment the user experience. A repository of GNOME extensions can be found on GNOME's official webpage and can be installed imperatively if needed by unpacking the extension in ~/.local/share/gnome-shell/extensions directory. Extensions can only be activated if it supports the GNOME release that it's installed alongside with.

However, Nix automatically packages all available GNOME extensions under the pkgs.gnomeExtensions attribute. Extensions which require additional dependencies are then manually packaged if needed. Installed extensions can be enabled graphically through the built-in "Extensions" application or through the gnome-extensions command line interface.

❄︎ /etc/nixos/configuration.nix

{
  environment.systemPackages = with pkgs; [
    gnomeExtensions.blur-my-shell
    gnomeExtensions.just-perfection
    gnomeExtensions.arc-menu
  ];
}

Configuration

dconf

Dconf is a low-level configuration system for storing and loading configurations. The dconf database is stored in a single binary file in ~/.config/dconf/user and contains all known configuration values for all applications and programs that use dconf (GNOME applications and shell, gtk, etc).

For example, the setting which controls the accent color of GNOME shell is located in the schema labeled /org/gnome/desktop/interface/ which contains the key accent-color which accepts a GVariant value of type enum (one of 'blue', 'teal', 'green', etc)

NixOS and Home Manager both provide an interface for declarative configuration of dconf settings exposed in programs.dconf and dconf modules respectively. This option accepts an attribute set whose names are schemas whose paired value is another attribute set whose names are keys and paired values as GVariant values.

Going back to the previous example, to set the accent color of GNOME in a declarative manner in NixOS as well as mapping the keyboard's "caps lock" key to "ctrl" you would write:

≡︎ /etc/nixos/configuration.nix

{
  programs.dconf.profiles.user.databases = [
    {
      lockAll = true; # prevents overriding
      settings = {
        "org/gnome/desktop/interface" = {
          accent-color = "blue";
        };
        "org/gnome/desktop/input-sources" = {
          xkb-options = ["ctrl:nocaps"];
        };
      };
    }
  ];
}

And the equivalent snippet in Home Manager:

❄︎ ~/.config/home-manager/home.nix

{
  dconf.enable = true;
  dconf.settings = {
    "org/gnome/desktop/interface" = {
      accent-color = "pink";
    };
    "org/gnome/desktop/input-sources" = {
      xkb-options = [ "ctrl:nocaps" ];
    };
  };
}

Note: Schemas in Nix are written without leading and trailing slashes. In addition, since dconf have more data types than the Nix language (for example, tuples), in some cases you'll need to convert Nix value to a GVariant value. You can achieve that by using function defined in lib.gvariant, they're documented here.

Extensions

Extensions are not activated by default when installed with Nix but can be configured to do so using the respective dconf modules. The schema is /org/gnome/shell/ with the key enabled-extensions which accepts a list of strings that represent extension UUIDs. If the extension was installed with Nix, then the UUID can be accessed by the extensionUuid attribute of the extension itself. Each extension's configuration can then be found under their corresponding schema in /org/gnome/shell/extensions/ and be configured as needed.

For example, in Home Manager, you could write:

❄︎ ~/.config/home-manager/home.nix

{
  dconf = {
    enable = true;
    settings = {
      "org/gnome/shell" = {
        disable-user-extensions = false; # enables user extensions
        enabled-extensions = [
          # Put UUIDs of extensions that you want to enable here.
          # If the extension you want to enable is packaged in nixpkgs,
          # you can easily get its UUID by accessing its extensionUuid
          # field (look at the following example).
          pkgs.gnomeExtensions.gsconnect.extensionUuid

          # Alternatively, you can manually pass UUID as a string.
          "blur-my-shell@aunetx"
          # ...
        ];
      };

      # Configure individual extensions
      "org/gnome/shell/extensions/blur-my-shell" = {
        brightness = 0.75;
        noise-amount = 0;
      };
    };
  };
}

Tips and tricks

Discover dconf settings

If you wish to discover the corresponding dconf entry for a given setting in a program, you can run `dconf watch /` inside of a terminal and change the setting graphically. For example, when changing toggling the Quick-Settings option "Dark Style" from "on" to "off" and back to "on," this will be the output:

$ dconf watch /
/org/gnome/desktop/interface/color-scheme
  'default'

/org/gnome/desktop/interface/color-scheme
  'prefer-dark'

Otherwise you can use the gsettings programs to inspect the schemas installed on your system. For example, to inspect all the keys contained within /org/gnome/desktop/background you could run:

$ gsettings list-keys org.gnome.desktop.background
color-shading-type
picture-opacity
picture-options
picture-uri
picture-uri-dark
primary-color
secondary-color
show-desktop-icons

Then to see the range of possible values for one of the keys such as picture-options you could then run:

$ gsettings range org.gnome.desktop.background picture-options
enum
'none'
'wallpaper'
'centered'
'scaled'
'stretched'
'zoom'
'spanned'

Which tells you that the key picture-options located in schema /org/gnome/desktop/background/ accepts a value of type enumeration (a single string value from a set of accepted values).

To run GNOME programs outside of GNOME

GNOME platform-based applications are largely self-contained, but they still depend, for one reason or another, on some global configuration. The gnome.nix module sets all the necessary options for you but if you are running customized set-up, you might need to replicate that yourself.

For instance, if you see the following error:

dconf-WARNING **: failed to commit changes to dconf: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

you should enable dconf module:

{
  programs.dconf.enable = true;
}

If you're using the default theme, GTK-3 applications may not respect the dark theme if they can't find the Adwaita. To fix it, make sure you have the gnome-themes-extra package installed:

{
  environment.systemPackages = [ pkgs.gnome-themes-extra ];
}

Systray Icons

To get systray icons, install the related GNOME shell extension

{
  environment.systemPackages = [ pkgs.gnomeExtensions.appindicator ];
}

And ensure gnome-settings-daemon udev rules are enabled:

{
  services.udev.packages = [ pkgs.gnome-settings-daemon ];
}

To run old applications

Some old applications use GConf service to store configuration. This has been deprecated for many years but some applications were abandoned before they managed to upgrade to a newer dconf system. If you are running such application and getting an error like:

GLib.GException: Failed to contact configuration server; the most common cause is a missing or misconfigured D-Bus session bus daemon. See http://projects.gnome.org/gconf/ for information

you need to add gnome2.GConf to the list of dbus packages in your configuration.nix:

{
  services.dbus.packages = with pkgs; [ gnome2.GConf ];
}

After applying the update restart your desktop session to refresh the user-specific dbus session.

Profiling (with sysprof)

Install sysprof as a system package (it won't work properly if installed against users). Then enable the associated service with

  services.sysprof.enable = true;

Automatic screen rotation

  hardware.sensor.iio.enable = true;

Dark mode

Change default color theme for all GTK4 applications to dark using Home Manager.

❄︎ ~/.config/home-manager/home.nix

{
  dconf = {
    enable = true;
    settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
  };
}

Troubleshoots

Automatic login

If you have enabled auto login (with GNOME) with something like

$ grep autoLogin /etc/nixos/configuration.nix

services.xserver.displayManager.autoLogin.enable = true;
services.xserver.displayManager.autoLogin.user = "account";

than add the following (as a workaround for a current (2023) problem)

# nano /etc/nixos/configuration.nix

{
  systemd.services."getty@tty1".enable = false;
  systemd.services."autovt@tty1".enable = false;
}

See also

• GNOME/Calendar