NixOS Wiki

GNOME: Difference between revisions

← Older edit
VisualWikitext
Klinger (talk | contribs)
trusted
903 edits
added link to nixos manual
Jasi (talk | contribs)
29 edits
m →GNOME desktop: fix typo
 
(75 intermediate revisions by 19 users not shown)
Line 1: Line 1:
 
[[{{PAGENAME}}]] (/(ɡ)noʊm/) is a [[:Category:Desktop environment|desktop environment]] that seeks to be "an independent computing platform for everyone."<ref>Official GNOME Project one-liner https://www.gnome.org/ </ref>
[[{{PAGENAME}}]] (/(ɡ)noʊm/) is a [[desktop environment]] known for its focus on being simple, intuitive, and easy to use. It is made by The GNOME Project and is composed entirely of free and open-source software. Its Mutter compositor supports both [[Wayland]] and X server, and the GNOME Shell user interface is customizable by extensions.


This article is an extension of the documentation in the [https://nixos.org/manual/nixos/stable/#chap-gnome NixOS manual].
This article is an extension of the documentation in the [https://nixos.org/manual/nixos/stable/#chap-gnome NixOS manual].


[https://gnome.org/ {{PAGENAME}}] is available as a [[module]] and can be enabled with <code>services.xserver.desktopManager</code>.
== Installation ==
== Installation ==


To use GNOME, add this to your configuration.nix:
=== GNOME desktop ===
To use the GNOME desktop environment on NixOS, the following configuration options must be set:


<syntaxHighlight lang=nix>
{{file|3={ config, pkgs, ... }:
services.xserver.enable = true;
services.xserver.displayManager.gdm.enable = true;
services.xserver.desktopManager.gnome.enable = true;
</syntaxHighlight>


=== Excluding GNOME Applications ===
{


To exclude certain applications that are installed by default with GNOME edit {{ic|configuration.nix}} as follows:
  # Pre 25.11
  services.xserver.enable = true;
  services.xserver.displayManager.gdm.enable = true;
  services.xserver.desktopManager.gnome.enable = true;


<syntaxhighlight lang="nixos">
   # As of 25.11
environment.gnome.excludePackages = (with pkgs; [
   services.displayManager.gdm.enable = true;
   # for packages that are pkgs.***
   services.desktopManager.gnome.enable = true;
   gnome-tour
  gnome-connections
]) ++ (with pkgs.gnome; [
   # for packages that are pkgs.gnome.***
  epiphany # web browser
  geary # email reader
  evince # document viewer
]);
</syntaxhighlight>


== Configuration ==
  # 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 ];


=== Managing Extensions ===
}|name=/etc/nixos/configuration.nix|lang=nix}}


GNOME extensions are managed and configured by the program "Extensions" that comes with GNOME.
Despite the options in NixOS versions before 25.11 being under the <code>xserver</code> 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).


Extensions can be installed with Nix, however they aren't enabled by default. To enable them the "Extensions" program can be used.
=== GNOME extensions ===
<syntaxhighlight lang="nixos">
GNOME offers support for changing/overhauling the user interface (GNOME Shell) through the use of ''[https://extensions.gnome.org/about/ Extensions].'' Extensions are bundles of third-party [https://gjs.guide/extensions/ 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 [https://extensions.gnome.org/ webpage] and can be installed imperatively if needed by unpacking the extension in <code>~/.local/share/gnome-shell/extensions</code> directory. Extensions can only be activated if it supports the GNOME release that it's installed alongside with.
environment.systemPackages = (with pkgs.gnomeExtensions; [
  blur-my-shell
  pop-shell
  # ***
]);
</syntaxhighlight>


To declaratively enable and configure, use of modules like home-manager you are required to configure dconf settings.
In addition, NixOS automatically packages all officially available GNOME extensions under the <code>pkgs.gnomeExtensions</code> 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 <code>gnome-extensions</code> command line interface.


<syntaxhighlight lang="nixos">
{{file|3={
dconf = {
  environment.systemPackages = with pkgs; [
        enable = true;
    gnomeExtensions.blur-my-shell
        settings = {
    gnomeExtensions.just-perfection
                "org/gnome/shell" = {
    gnomeExtensions.arc-menu
                        disabled-user-extensions = false; # enables user extensions (disabled by default)
  ];
                        enabled-extensions = [
}|name=/etc/nixos/configuration.nix|lang=nix}}
                                "blur-my-shell@aunetx"
== Configuration ==
                                # ****
                        ];
                };


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


To learn about settings that can be configured with dconf either look into "dconf editor" program or type <syntaxhighlight lang="shell">dconf watch /</syntaxhighlight> in the terminal and change settings from the GUI and see which options are responsible for that component/element.
Dconf is a low-level configuration system for storing and loading configurations. The dconf database is stored in a single binary file in <code>~/.config/dconf/user</code> 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 <code>/org/gnome/desktop/interface/</code> which contains the ''key'' <code>accent-color</code> which accepts a GVariant ''value'' of type <code>enum</code> (one of <code>'blue'</code>, <code>'teal'</code>, <code>'green'</code>, etc)


=== Dark mode ===
NixOS and Home Manager both provide an interface for declarative configuration of dconf settings exposed in <code>programs.dconf</code> and <code>dconf</code> modules respectively.


Change default color theme for all GTK4 applications to dark using [[Home Manager]]. Change <code>myuser</code> to the user you want to apply the configuration to.
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:


<syntaxhighlight lang="nix">
{{file|3={
home-manager.users.myuser = {
  programs.dconf.profiles.user.databases = [
        dconf = {
    {
                enable = true;
      lockAll = true; # prevents overriding
                settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
      settings = {
        "org/gnome/desktop/interface" = {
          accent-color = "blue";
        };
        "org/gnome/desktop/input-sources" = {
          xkb-options = [ "ctrl:nocaps" ];
         };
         };
};
      };
</syntaxhighlight>
    }
  ];
}|name=/etc/nixos/configuration.nix|lang=nix}}


== Tips and tricks ==
And the equivalent snippet in Home Manager:


=== To run GNOME programs outside of GNOME ===
{{file|3={
  dconf.enable = true;
  dconf.settings = {
    "org/gnome/desktop/interface" = {
      accent-color = "blue";
    };
    "org/gnome/desktop/input-sources" = {
      xkb-options = [ "ctrl:nocaps" ];
    };
  };
}|name=~/.config/home-manager/home.nix|lang=nix}}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 <code>lib.gvariant</code>, they're documented [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-gvariant 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.<syntaxhighlight lang="bash">
$ dconf reset -f /
</syntaxhighlight>


GNOME platform-based applications are largely [https://nixos.org/nixpkgs/manual/#sec-language-gnome self-contained], but they still depend, for one reason or another, on some global configuration. The {{ic|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.
==== 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 <code>/org/gnome/shell/</code> with the key <code>enabled-extensions</code> 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 <code>extensionUuid</code> attribute of the extension itself. Each extension's configuration can then be found under their corresponding schema in <code>/org/gnome/shell/extensions/</code> and be configured as needed.


For instance, if you see the following error:
For example, in Home Manager, you could write:


<syntaxhighlight lang="text">
{{file|3={
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
  dconf = {
</syntaxhighlight>
    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


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


<syntaxHighlight lang=nix>
      # Configure individual extensions
programs.dconf.enable = true;
      "org/gnome/shell/extensions/blur-my-shell" = {
</syntaxHighlight>
        brightness = 0.75;
        noise-amount = 0;
      };
    };
  };
}|name=~/.config/home-manager/home.nix|lang=nix}}


Many applications rely heavily on having an icon theme available, GNOME’s Adwaita is a good choice but most recent icon themes should work as well.
== Tips and tricks ==


<syntaxHighlight lang=nix>
=== GNOME power user apps ===
environment.systemPackages = [ gnome.adwaita-icon-theme ];
Both GNOME Tweaks (accessible as <code>gnome-tweaks</code>) and [https://gitlab.gnome.org/TheEvilSkeleton/Refine Refine] (accessible as <code>refine</code>) 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).
</syntaxHighlight>


=== Systray Icons ===
The GNOME shell extension [https://extensions.gnome.org/extension/3843/just-perfection/ Just Perfection] also allows for customizing nearly all parts of the GNOME shell interface.


To get systray icons, install the related gnome shell extension
=== 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.
{{File|3={
  qt = {
    enable = true;
    platformTheme = "gnome";
    style = "adwaita-dark";
  };
}|name=/etc/nixos/configuration.nix|lang=nix}}
For other themes, you may need the packages <code>libsForQt5.qt5ct</code> and <code>libsForQt5.qtstyleplugin-kvantum</code> and a symlink from <code>~/.config/Kvantum/</code> to your theme package. Here is an example using Arc-Dark and [[Home Manager]]. In the Home Manager configuration:
{{File|3={
  qt = {
    enable = true;
    platformTheme = "qtct";
    style = "kvantum";
  };


<syntaxHighlight lang=nix>
  xdg.configFile = {
environment.systemPackages = with pkgs; [ gnomeExtensions.appindicator ];
    "Kvantum/ArcDark".source = "${pkgs.arc-kde-theme}/share/Kvantum/ArcDark";
</syntaxHighlight>
    "Kvantum/kvantum.kvconfig".text = "[General]\ntheme=ArcDark";
  };
}|name=~/.config/home-manager/home.nix|lang=nix}}
For more details, see [https://discourse.nixos.org/t/guide-to-installing-qt-theme/35523/2 this] forum post.{{Note|Qt integration with the adwaita style isn't perfect and your mileage may vary.}}


And ensure gnome-settings-daemon udev rules are enabled :
=== 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:
{{File|3={
  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
          ];
        };
      };
    }
  ];
}|name=/etc/nixos/configuration.nix|lang=nix}}


<syntaxHighlight lang=nix>
=== Discover dconf settings ===
services.udev.packages = with pkgs; [ gnome.gnome-settings-daemon ];
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:<syntaxhighlight lang="shell-session">
</syntaxHighlight>
$ dconf watch /
/org/gnome/desktop/interface/color-scheme
  'default'


=== To run old applications ===
/org/gnome/desktop/interface/color-scheme
  'prefer-dark'
</syntaxhighlight>Otherwise you can use the gsettings programs to inspect the schemas installed on your system. For example, to inspect all the keys contained within <code>/org/gnome/desktop/background</code> you could run:<syntaxhighlight lang="shell-session">
$ 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


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:
</syntaxhighlight>Then to see the range of possible values for one of the keys such as <code>picture-options</code> you could then run:<syntaxhighlight lang="shell-session">
$ gsettings range org.gnome.desktop.background picture-options
enum
'none'
'wallpaper'
'centered'
'scaled'
'stretched'
'zoom'
'spanned'


<syntaxHighlight lang=text>
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
</syntaxHighlight>


you need to add {{ic|gnome2.GConf}} to the list of dbus packages in your {{ic|configuration.nix}}:
</syntaxhighlight>Which tells you that the ''key'' <code>picture-options</code> located in ''schema'' <code>/org/gnome/desktop/background/</code> accepts a ''value'' of type enumeration (a single string value from a set of accepted values).  


<syntaxHighlight lang=nix>
=== Enable system tray icons ===
services.dbus.packages = with pkgs; [ gnome2.GConf ];
GNOME does not currently support system tray icons. However, Ubuntu has created an [https://extensions.gnome.org/extension/615/appindicator-support/ extension] that implements this in the top bar. You can install this extension with the following in NixOS:
</syntaxHighlight>
{{File|3={
  environment.systemPackages = [ pkgs.gnomeExtensions.appindicator  ];
  services.udev.packages = [ pkgs.gnome-settings-daemon ];
}|name=/etc/nixos/configuration.nix|lang=nix}}


After applying the update restart your desktop session to refresh the user-specific dbus session.
=== Profiling (with sysprof) ===


=== Dynamic triple buffering ===
Install {{ic|sysprof}} as a ''system'' package (it won't work properly if installed against users). Then enable the associated service with


Big [https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1441 merge request] against Mutter improves the performance of the window manager by a lot (and is already used by Ubuntu). Not merged into nixpkgs due to [https://github.com/NixOS/nixpkgs/issues/197181 philosophy of nixpkgs], but users are free to add this overlay to get it too.
<syntaxhighlight lang="nix">
  services.sysprof.enable = true;
</syntaxhighlight>


For NixOS 23.11 (gnome 45), add the following:
=== Automatic screen rotation ===


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
nixpkgs.overlays = [
  hardware.sensor.iio.enable = true;
        (final: prev: {
                gnome = prev.gnome.overrideScope (gnomeFinal: gnomePrev: {
                        mutter = gnomePrev.mutter.overrideAttrs ( old: {
                                src = pkgs.fetchgit {
                                        url = "https://gitlab.gnome.org/vanvugt/mutter.git";
                                        rev = "0b896518b2028d9c4d6ea44806d093fd33793689";
                                        sha256 = "sha256-mzNy5GPlB2qkI2KEAErJQzO//uo8yO0kPQUwvGDwR4w=";
                                };
                        });
                });
        })
];
</syntaxhighlight>
</syntaxhighlight>


For NixOS 24.05 (gnome 46), add the following:
=== Dark mode ===


<syntaxhighlight lang="nix">
Change default color theme for all GTK4 applications to dark using [[Home Manager]].
nixpkgs.overlays = [
        (final: prev: {
                gnome = prev.gnome.overrideScope (gnomeFinal: gnomePrev: {
                        mutter = gnomePrev.mutter.overrideAttrs ( old: {
                                src = pkgs.fetchgit {
                                        url = "https://gitlab.gnome.org/vanvugt/mutter.git";
                                        rev = "663f19bc02c1b4e3d1a67b4ad72d644f9b9d6970";
                                        sha256 = "sha256-I1s4yz5JEWJY65g+dgprchwZuPGP9djgYXrMMxDQGrs=";
                                };
                        });
                });
        })
];


</syntaxhighlight>
{{file|~/.config/home-manager/home.nix|nix|<nowiki>
{
  dconf = {
    enable = true;
    settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
  };
}
</nowiki>}}


You might need to disable aliases to make it work:
=== Excluding GNOME Applications ===


<syntaxHighlight lang=nix>
To exclude certain applications that are installed by default with GNOME, set the {{nixos:option|environment.gnome.excludePackages}} module option (Optional Packages: [https://github.com/NixOS/nixpkgs/blob/nixos-unstable/nixos/modules/services/desktop-managers/gnome.nix#L449-L471 gnome.nix]):
nixpkgs.config.allowAliases = false;
</syntaxHighlight>


=== Profiling (with sysprof) ===
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
  environment.gnome.excludePackages = with pkgs; [
    totem
  ];
</nowiki>}}


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


<syntaxHighlight lang=nix>
=== Missing cursor/cursor is a white box ===
services.sysprof.enable = true;
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.<syntaxhighlight lang="bash">
</syntaxHighlight>
$ dconf reset -f /
</syntaxhighlight>


=== Automatic screen rotation ===
=== Running GConf-based applications ===


<syntaxHighlight lang=nix>
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:
hardware.sensor.iio.enable = true;
</syntaxHighlight>


== Troubleshoots ==
<syntaxhighlight lang="text">
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
</syntaxhighlight>


=== Change user's profile picture ===
you will need to add <code>pkgs.gnome2.GConf</code> to the list of dbus packages in your NixOS configuration like so:
Currently there is no way to change the user's profile picture using Gnome Control Center [https://github.com/NixOS/nixpkgs/issues/10025 (see this issue)] and currently there is no plan to support it officially in NixOS. However, you can modify it by copying the profile picture that you want to the path '''/home/$USER/.face''' as a workaround, i.e.


<syntaxHighlight lang=console>
{{File|3={
$ mv /path/to/image.jpg ~/.face
  services.dbus.packages = with pkgs; [ gnome2.GConf ];
</syntaxHighlight>
}|name=/etc/nixos/configuration.nix|lang=nix}}


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


If you have enabled [https://help.gnome.org/admin/system-admin-guide/stable/login-automatic.html.en auto login] (with <!-- [[GDM]] -->[[{{PAGENAME}}]]) with something like
=== Automatic login ===
: <syntaxHighlight lang=bash>
grep autoLogin /etc/nixos/configuration.nix
</syntaxHighlight>
<syntaxHighlight lang=nix>
services.xserver.displayManager.autoLogin.enable = true;
services.xserver.displayManager.autoLogin.user = "account";
</syntaxHighlight>
than add the following (as a workaround for a current (2023)<ref>https://github.com/NixOS/nixpkgs/issues/103746#issuecomment-945091229</ref> problem)
: <syntaxHighlight lang=console># nano /etc/nixos/configuration.nix</syntaxHighlight>
<syntaxHighlight lang=nix>
systemd.services."getty@tty1".enable = false;
systemd.services."autovt@tty1".enable = false;
</syntaxHighlight>
.


== Also see ==
As a potential workaround<ref>https://github.com/NixOS/nixpkgs/issues/103746#issuecomment-945091229</ref> for automatic login, include this in your NixOS configuration:


[[GNOME/Calendar]]
{{File|3={
  services.xserver.displayManager.autoLogin.enable = true;
  services.xserver.displayManager.autoLogin.user = "account";
 
  systemd.services."getty@tty1".enable = false;
  systemd.services."autovt@tty1".enable = false;
}|name=/etc/nixos/configuration.nix|lang=nix}}


=== GDM does not show user ===
The GDM (GNOME Display Manager) will not display a user if their default shell is not listed in <code>/etc/shells</code>. If your shell, such as zsh, is not included in <code>/etc/shells</code>, you need to add it to the configuration.{{File|3={
  environment.shells = with pkgs; [ zsh ];
}|name=/etc/nixos/configuration.nix|lang=nix}}
:
== References ==
[[Category:Desktop environment]]
[[Category:Desktop environment]]
[[Category:Applications]]
[[Category:Applications]]
[[Category:NixOS Manual]]
[[Category:NixOS Manual]]
[[Category:GNOME]]
Retrieved from "https://wiki.nixos.org/wiki/GNOME"