A markdown draft of docs in the nixos manual for GNOME.

gnome3.md

GNOME Desktop

Enabling GNOME

All of the core apps, optional apps, and games from GNOME are available.

To enable the GNOME desktop use:

services.xserver.desktopManager.gnome3.enable = true;

and it is also recommended to enable:

services.xserver.displayManager.gdm

as the display-manager.

The default applications used in NixOS are very minimal, inspired frrom the defaults used in gnome-build-meta.

GNOME without the apps

If you'd like to only use the GNOME desktop and not the apps, you can disable them with:

services.gnome3.core-utilities.enable = false;

and none will be installed.

If you'd only like certain omissions you can use environment.gnome3.excludePackages. Note, this only removes things installed in the gnome3 module from environment.systemPackages. Certain applications require an entire nixos module, like evince or geary. Search for GNOME apps in programs to find which option to disable.

GNOME games

You can install all of the GNOME games with:

services.gnome3.games.enable = true;

Enabling GNOME Flashback

You can enable the default GNOME Flashback session, which uses metacity, with:

 services.xserver.desktopManager.gnome3.flashback.enableMetacity = true;

It's also possible to create custom sessions with services.xserver.desktopManager.gnome3.customSessions.

The following example uses xmonad:

services.xserver.desktopManager.gnome3.flashback.customSessions = [{
  wmName = "xmonad";
  wmLabel = "XMonad";
  wmCommand = "${pkgs.haskellPackages.xmonad}/bin/xmonad";
}];

GDM

If you want to use GNOME wayland and NVidia you need to enable:

services.xserver.displayManager.gdm.nvidiaWayland = true;

as the default configuration will forbid this.

Icons and GTK Themes

Icon themes and GTK themes don't require any special option to install in NixOS.

You can add them to environment.systemPackages and switch to them with GNOME Tweaks. If you'd like to do this manually in dconf, change the values of the following keys:

/org/gnome/desktop/interface/gtk-theme
/org/gnome/desktop/interface/icon-theme

in Dconf Editor

Shell Extensions

All shell extensions are packaged under the gnomeExtensions attribute.

You can install them like any other package:

environment.systemPackages = [
  gnomeExtensions.dash-to-dock
  gnomeExtensions.gsconnect
  gnomeExtensions.mpris-indicator-button
];

Unfortunately, we lack a way for these to be managed in a completely declarative way. So you have to enable them manually with an Extensions application. It's possible to use a GSettings Override for this on org.gnome.shell.enabled-extensions, but those will only influence the default value.

GSettings Overrides

GSettings Overrides can be used to adjust the default settings for the GNOME desktop and apps.

Using this will allow you to pre-seed user defaults before you even start the session.

You can do this by using the extraGSettingsOverrides option.

Take note that whatever packages you want to override gsettings for, you need to add them to extraGSettingsOverridePackages.

If you need to a tool to explore which gsettings you can set, you can use dconf-editor.

Example

services.xserver.desktopManager.gnome3 = {
  extraGSettingsOverrides = ''
    # Change default background
    [org.gnome.desktop.background]
    picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue}'

    # Favorite apps in gnome-shell
    [org.gnome.shell]
    favorite-apps=['org.gnome.Photos.desktop', 'org.gnome.Nautilus.desktop']
  '';

  extraGSettingsOverridePackages = [
    pkgs.gsettings-desktop-schemas # for org.gnome.desktop
    pkgs.gnome3.gnome-shell # for org.gnome.shell
  ];
};

FAQ

Can I use LightDM with GNOME?

Yes you can, and any other display-manager in NixOS.

However, it currently doesn't work correctly for the wayland session of GNOME yet.

See this issue.

Sometimes nixos-rebuild switch kills my session

This is a known issue without any workarounds. If you're doing a fairly large upgrade, it's probably safer to use nixos-rebuild boot.

1. services.xserver.displayManager.gdm should be block for easier copy pasting.

Did you mean "and it is also recommended to enable services.xserver.displayManager.gdm as a display-manager as well." should be code a block?

2. GNOME OS not really a thing

Will fix.

3. Search for GNOME apps in programs to find which option to disable. ­– not sure what doe this mean.

The header is GNOME without the apps.
One would search for file-roller https://nixos.org/nixos/options.html#file-roller (GNOME app) and that is the option to disable since it's default. Though this isn't really intuitive. If only the module could self document what programs it enables.

4. any preferred application?

☑️

5. GNOME Tweaks or gnome-shell-extensions-prefs → Extensions application

☑️

Did you mean "and it is also recommended to enable services.xserver.displayManager.gdm as a display-manager as well." should be code a block?

Yup, it is more convenient if the code can be copied as is.

One would search for file-roller nixos.org/nixos/options.html#file-roller (GNOME app) and that is the option to disable since it's default. Though this isn't really intuitive. If only the module could self document what programs it enables.

Maybe we should link to the module so that users can see what is enabled.

Continued in NixOS/nixpkgs#86288