GNOME

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

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

Installation

GNOME desktop

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

❄︎ /etc/nixos/configuration.nix

{ config, pkgs, ... }:

{

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

  # To disable installing GNOME's suite of applications
  # and only be left with GNOME shell.
  services.gnome.core-apps.enable = false;
  services.gnome.core-developer-tools.enable = false;
  services.gnome.games.enable = false;
  environment.gnome.excludePackages = with pkgs; [ gnome-tour gnome-user-docs ];

}

Despite the options in NixOS versions before 25.11 being under the xserver module, GNOME uses Wayland by default. NixOS 25.11 and later removes 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.

In addition, NixOS automatically packages all officially 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.

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 = "blue";
    };
    "org/gnome/desktop/input-sources" = {
      xkb-options = [ "ctrl:nocaps" ];
    };
  };
}

Thus the settings attribute accepts an attribute set whose keys are schemas with each schema's value being a nested attribute set of the schema's keys with their appropriate GVariant value.

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 the functions defined under lib.gvariant, they're documented here.

If you wish to revert all dconf settings back to their default state (reset GNOME essentially) then use the following command which resets all schemas directories available on your system, note that this will affect all programs that use dconf, including GNOME apps and extensions.

$ dconf reset -f /

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 = true; # Optionally disable user extensions entirely
        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

GNOME power user apps

Both GNOME Tweaks (accessible as gnome-tweaks) and Refine (accessible as refine) allow you to change certain GNOME settings that are hidden by default (such as interface font, window decoration buttons like maximize/minimize, icon themes and GTK themes, etc).

The GNOME shell extension Just Perfection also allows for customizing nearly all parts of the GNOME shell interface.

GNOME Qt integration

Using the following example configuration, Qt applications will have a look similar to the adwaita style used by GNOME using a dark theme.

❄︎ /etc/nixos/configuration.nix

{
  qt = {
    enable = true;
    platformTheme = "gnome";
    style = "adwaita-dark";
  };
}

For other themes, you may need the packages libsForQt5.qt5ct and libsForQt5.qtstyleplugin-kvantum and a symlink from ~/.config/Kvantum/ to your theme package. Here is an example using Arc-Dark and Home Manager. In the Home Manager configuration:

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

{
  qt = {
    enable = true;
    platformTheme = "qtct";
    style = "kvantum";
  };

  xdg.configFile = {
    "Kvantum/ArcDark".source = "${pkgs.arc-kde-theme}/share/Kvantum/ArcDark";
    "Kvantum/kvantum.kvconfig".text = "[General]\ntheme=ArcDark";
  };
}

For more details, see this forum post.

Note: Qt integration with the adwaita style isn't perfect and your mileage may vary.

Experimental settings

GNOME has a number of experimental settings for features not fully completed and thus hidden from the user. As of GNOME 48, these are the experimental features you may want to use:

❄︎ /etc/nixos/configuration.nix

{
  programs.dconf.profiles.user.databases = [
    {
      settings = {
        "org/gnome/mutter" = {
          experimental-features = [
            "scale-monitor-framebuffer" # Enables fractional scaling (125% 150% 175%)
            "variable-refresh-rate" # Enables Variable Refresh Rate (VRR) on compatible displays
            "xwayland-native-scaling" # Scales Xwayland applications to look crisp on HiDPI screens
          ];
        };
      };
    }
  ];
}

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

Enable system tray icons

GNOME does not currently support system tray icons. However, Ubuntu has created an extension that implements this in the top bar. You can install this extension with the following in NixOS:

❄︎ /etc/nixos/configuration.nix

{
  environment.systemPackages = [ pkgs.gnomeExtensions.appindicator  ];
  services.udev.packages = [ pkgs.gnome-settings-daemon ];
}

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";
  };
}

Excluding GNOME Applications

To exclude certain applications that are installed by default with GNOME, set the environment.gnome.excludePackages module option (Optional Packages: gnome.nix):

❄︎ /etc/nixos/configuration.nix

  environment.gnome.excludePackages = with pkgs; [
    totem
  ];

Troubleshooting

Missing cursor/cursor is a white box

This occurs when installing GNOME from an existing NixOS installation that used a different desktop environment that modified dconf (most likely switching from KDE to GNOME). To easily fix this: reset all dconf settings.

$ dconf reset -f /

Running GConf-based applications

There exist very old applications which use the deprecated GConf service to store configuration. If you are running such an application and are 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 will need to add pkgs.gnome2.GConf to the list of dbus packages in your NixOS configuration like so:

❄︎ /etc/nixos/configuration.nix

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

After rebuilding your configuration, restart your desktop session to have GConf take effect.

Automatic login

As a potential workaround for automatic login, include this in your NixOS configuration:

❄︎ /etc/nixos/configuration.nix

{
  services.xserver.displayManager.autoLogin.enable = true;
  services.xserver.displayManager.autoLogin.user = "account";
  
  systemd.services."getty@tty1".enable = false;
  systemd.services."autovt@tty1".enable = false;
}

GDM does not show user

The GDM (GNOME Display Manager) will not display a user if their default shell is not listed in /etc/shells. If your shell, such as zsh, is not included in /etc/shells, you need to add it to the configuration.

❄︎ /etc/nixos/configuration.nix

{
  environment.shells = with pkgs; [ zsh ];
}