NixOS Wiki

GNOME: Difference between revisions

← Older edit
VisualWikitext
reformat code
Jasi (talk | contribs)
29 edits
m →GNOME desktop: fix typo
 
(71 intermediate revisions by 18 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:
 
{{file|3={ 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;


<syntaxHighlight lang=nix>
  # To disable installing GNOME's suite of applications
services.xserver.enable = true;
  # and only be left with GNOME shell.
services.xserver.displayManager.gdm.enable = true;
  services.gnome.core-apps.enable = false;
services.xserver.desktopManager.gnome.enable = true;
  services.gnome.core-developer-tools.enable = false;
</syntaxHighlight>
  services.gnome.games.enable = false;
  environment.gnome.excludePackages = with pkgs; [ gnome-tour gnome-user-docs ];


=== Excluding GNOME Applications ===
}|name=/etc/nixos/configuration.nix|lang=nix}}
 
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).


To exclude certain applications that are installed by default with GNOME edit {{ic|configuration.nix}} as follows:
=== GNOME extensions ===
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.


<syntaxhighlight lang="nixos">
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.
environment.gnome.excludePackages = (with pkgs; [
  # for packages that are pkgs.***
  gnome-tour
  gnome-connections
]) ++ (with pkgs.gnome; [
  # for packages that are pkgs.gnome.***
  epiphany # web browser
  geary # email reader
  evince # document viewer
]);
</syntaxhighlight>


{{file|3={
  environment.systemPackages = with pkgs; [
    gnomeExtensions.blur-my-shell
    gnomeExtensions.just-perfection
    gnomeExtensions.arc-menu
  ];
}|name=/etc/nixos/configuration.nix|lang=nix}}
== Configuration ==
== Configuration ==


=== Managing Extensions ===
=== dconf ===


GNOME extensions are managed and configured by the program "Extensions" that comes with GNOME.
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).


Extensions can be installed with Nix, however they aren't enabled by default. To enable them the "Extensions" program can be used.
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)
<syntaxhighlight lang="nixos">
 
environment.systemPackages = (with pkgs.gnomeExtensions; [
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.
   blur-my-shell
 
  pop-shell
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:
   # ***
 
]);
{{file|3={
  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" ];
        };
      };
    }
  ];
}|name=/etc/nixos/configuration.nix|lang=nix}}
 
And the equivalent snippet in Home Manager:
 
{{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>
</syntaxhighlight>


To declaratively enable and configure, use of modules like home-manager you are required to configure dconf settings.
==== 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.


<syntaxhighlight lang="nixos">
For example, in Home Manager, you could write:
{
 
{{file|3={
   dconf = {
   dconf = {
     enable = true;
     enable = true;
     settings = {
     settings = {
       "org/gnome/shell" = {
       "org/gnome/shell" = {
         disabled-user-extensions = false; # enables user extensions (disabled by default)
         # disable-user-extensions = true; # Optionally disable user extensions entirely
         enabled-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"
           "blur-my-shell@aunetx"
           # ****
           # ...
         ];
         ];
       };
       };
Line 69: Line 119:
     };
     };
   };
   };
}
}|name=~/.config/home-manager/home.nix|lang=nix}}
</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.
== Tips and tricks ==


=== Dark mode ===
=== GNOME power user apps ===
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).


Change default color theme for all GTK4 applications to dark using [[Home Manager]].
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.  


<syntaxhighlight lang="nix">
=== 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.
   dconf = {
{{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;
     enable = true;
     settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
     platformTheme = "qtct";
    style = "kvantum";
   };
   };
}
</syntaxhighlight>


== Tips and tricks ==
  xdg.configFile = {
    "Kvantum/ArcDark".source = "${pkgs.arc-kde-theme}/share/Kvantum/ArcDark";
    "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.}}


=== To run GNOME programs outside of GNOME ===
=== 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}}


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.
=== 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:<syntaxhighlight lang="shell-session">
$ dconf watch /
/org/gnome/desktop/interface/color-scheme
  'default'


For instance, if you see the following error:
/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


<syntaxhighlight lang="text">
</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">
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
$ gsettings range org.gnome.desktop.background picture-options
</syntaxhighlight>
enum
'none'
'wallpaper'
'centered'
'scaled'
'stretched'
'zoom'
'spanned'


you should enable dconf module:


<syntaxHighlight lang=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).
programs.dconf.enable = true;
</syntaxHighlight>


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.
=== Enable system tray icons ===
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:
{{File|3={
  environment.systemPackages = [ pkgs.gnomeExtensions.appindicator  ];
  services.udev.packages = [ pkgs.gnome-settings-daemon ];
}|name=/etc/nixos/configuration.nix|lang=nix}}


<syntaxHighlight lang=nix>
=== Profiling (with sysprof) ===
environment.systemPackages = [ gnome.adwaita-icon-theme ];
</syntaxHighlight>


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


To get systray icons, install the related gnome shell extension
<syntaxhighlight lang="nix">
  services.sysprof.enable = true;
</syntaxhighlight>


<syntaxHighlight lang=nix>
=== Automatic screen rotation ===
environment.systemPackages = with pkgs; [ gnomeExtensions.appindicator ];
</syntaxHighlight>


And ensure gnome-settings-daemon udev rules are enabled :
<syntaxhighlight lang="nix">
  hardware.sensor.iio.enable = true;
</syntaxhighlight>


<syntaxHighlight lang=nix>
=== Dark mode ===
services.udev.packages = with pkgs; [ gnome.gnome-settings-daemon ];
</syntaxHighlight>


=== To run old applications ===
Change default color theme for all GTK4 applications to dark using [[Home Manager]].
 
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 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 lang=nix>
services.dbus.packages = with pkgs; [ gnome2.GConf ];
</syntaxHighlight>
 
After applying the update restart your desktop session to refresh the user-specific dbus session.


=== Dynamic triple buffering ===
{{file|~/.config/home-manager/home.nix|nix|<nowiki>
 
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.
 
For NixOS 24.05 (gnome 46), add the following to your NixOS configuration:
 
<syntaxhighlight lang="nixos">
{
{
   nixpkgs.overlays = [
   dconf = {
     (final: prev: {
     enable = true;
      gnome = prev.gnome.overrideScope (
    settings."org/gnome/desktop/interface".color-scheme = "prefer-dark";
        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>
</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"