depot/third_party/nixpkgs/nixos/modules/services/x11/desktop-managers/gnome.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-gnome">
  <title>GNOME Desktop</title>
  <para>
    GNOME provides a simple, yet full-featured desktop environment with
    a focus on productivity. Its Mutter compositor supports both Wayland
    and X server, and the GNOME Shell user interface is fully
    customizable by extensions.
  </para>
  <section xml:id="sec-gnome-enable">
    <title>Enabling GNOME</title>
    <para>
      All of the core apps, optional apps, games, and core developer
      tools from GNOME are available.
    </para>
    <para>
      To enable the GNOME desktop use:
    </para>
    <programlisting>
services.xserver.desktopManager.gnome.enable = true;
services.xserver.displayManager.gdm.enable = true;
</programlisting>
    <note>
      <para>
        While it is not strictly necessary to use GDM as the display
        manager with GNOME, it is recommended, as some features such as
        screen lock
        <link linkend="sec-gnome-faq-can-i-use-lightdm-with-gnome">might
        not work</link> without it.
      </para>
    </note>
    <para>
      The default applications used in NixOS are very minimal, inspired
      by the defaults used in
      <link xlink:href="https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/40.0/elements/core/meta-gnome-core-utilities.bst">gnome-build-meta</link>.
    </para>
    <section xml:id="sec-gnome-without-the-apps">
      <title>GNOME without the apps</title>
      <para>
        If you’d like to only use the GNOME desktop and not the apps,
        you can disable them with:
      </para>
      <programlisting>
services.gnome.core-utilities.enable = false;
</programlisting>
      <para>
        and none of them will be installed.
      </para>
      <para>
        If you’d only like to omit a subset of the core utilities, you
        can use
        <xref linkend="opt-environment.gnome.excludePackages" />. Note
        that this mechanism can only exclude core utilities, games and
        core developer tools.
      </para>
    </section>
    <section xml:id="sec-gnome-disabling-services">
      <title>Disabling GNOME services</title>
      <para>
        It is also possible to disable many of the
        <link xlink:href="https://github.com/NixOS/nixpkgs/blob/b8ec4fd2a4edc4e30d02ba7b1a2cc1358f3db1d5/nixos/modules/services/x11/desktop-managers/gnome.nix#L329-L348">core
        services</link>. For example, if you do not need indexing files,
        you can disable Tracker with:
      </para>
      <programlisting>
services.gnome.tracker-miners.enable = false;
services.gnome.tracker.enable = false;
</programlisting>
      <para>
        Note, however, that doing so is not supported and might break
        some applications. Notably, GNOME Music cannot work without
        Tracker.
      </para>
    </section>
    <section xml:id="sec-gnome-games">
      <title>GNOME games</title>
      <para>
        You can install all of the GNOME games with:
      </para>
      <programlisting>
services.gnome.games.enable = true;
</programlisting>
    </section>
    <section xml:id="sec-gnome-core-developer-tools">
      <title>GNOME core developer tools</title>
      <para>
        You can install GNOME core developer tools with:
      </para>
      <programlisting>
services.gnome.core-developer-tools.enable = true;
</programlisting>
    </section>
  </section>
  <section xml:id="sec-gnome-enable-flashback">
    <title>Enabling GNOME Flashback</title>
    <para>
      GNOME Flashback provides a desktop environment based on the
      classic GNOME 2 architecture. You can enable the default GNOME
      Flashback session, which uses the Metacity window manager, with:
    </para>
    <programlisting>
services.xserver.desktopManager.gnome.flashback.enableMetacity = true;
</programlisting>
    <para>
      It is also possible to create custom sessions that replace
      Metacity with a different window manager using
      <xref linkend="opt-services.xserver.desktopManager.gnome.flashback.customSessions" />.
    </para>
    <para>
      The following example uses <literal>xmonad</literal> window
      manager:
    </para>
    <programlisting>
services.xserver.desktopManager.gnome.flashback.customSessions = [
  {
    wmName = &quot;xmonad&quot;;
    wmLabel = &quot;XMonad&quot;;
    wmCommand = &quot;${pkgs.haskellPackages.xmonad}/bin/xmonad&quot;;
    enableGnomePanel = false;
  }
];
</programlisting>
  </section>
  <section xml:id="sec-gnome-icons-and-gtk-themes">
    <title>Icons and GTK Themes</title>
    <para>
      Icon themes and GTK themes don’t require any special option to
      install in NixOS.
    </para>
    <para>
      You can add them to
      <xref linkend="opt-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:
    </para>
    <programlisting>
/org/gnome/desktop/interface/gtk-theme
/org/gnome/desktop/interface/icon-theme
</programlisting>
    <para>
      in <literal>dconf-editor</literal>
    </para>
  </section>
  <section xml:id="sec-gnome-shell-extensions">
    <title>Shell Extensions</title>
    <para>
      Most Shell extensions are packaged under the
      <literal>gnomeExtensions</literal> attribute. Some packages that
      include Shell extensions, like <literal>gnome.gpaste</literal>,
      don’t have their extension decoupled under this attribute.
    </para>
    <para>
      You can install them like any other package:
    </para>
    <programlisting>
environment.systemPackages = [
  gnomeExtensions.dash-to-dock
  gnomeExtensions.gsconnect
  gnomeExtensions.mpris-indicator-button
];
</programlisting>
    <para>
      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 is possible to use a
      <link linkend="sec-gnome-gsettings-overrides">GSettings
      override</link> for this on
      <literal>org.gnome.shell.enabled-extensions</literal>, but that
      will only influence the default value.
    </para>
  </section>
  <section xml:id="sec-gnome-gsettings-overrides">
    <title>GSettings Overrides</title>
    <para>
      Majority of software building on the GNOME platform use GLib’s
      <link xlink:href="https://developer.gnome.org/gio/unstable/GSettings.html">GSettings</link>
      system to manage runtime configuration. For our purposes, the
      system consists of XML schemas describing the individual
      configuration options, stored in the package, and a settings
      backend, where the values of the settings are stored. On NixOS,
      like on most Linux distributions, dconf database is used as the
      backend.
    </para>
    <para>
      <link xlink:href="https://developer.gnome.org/gio/unstable/GSettings.html#id-1.4.19.2.9.25">GSettings
      vendor overrides</link> can be used to adjust the default values
      for settings of the GNOME desktop and apps by replacing the
      default values specified in the XML schemas. Using overrides will
      allow you to pre-seed user settings before you even start the
      session.
    </para>
    <warning>
      <para>
        Overrides really only change the default values for GSettings
        keys so if you or an application changes the setting value, the
        value set by the override will be ignored. Until
        <link xlink:href="https://github.com/NixOS/nixpkgs/issues/54150">NixOS’s
        dconf module implements changing values</link>, you will either
        need to keep that in mind and clear the setting from the backend
        using <literal>dconf reset</literal> command when that happens,
        or use the
        <link xlink:href="https://nix-community.github.io/home-manager/options.html#opt-dconf.settings">module
        from home-manager</link>.
      </para>
    </warning>
    <para>
      You can override the default GSettings values using the
      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverrides" />
      option.
    </para>
    <para>
      Take note that whatever packages you want to override GSettings
      for, you need to add them to
      <xref linkend="opt-services.xserver.desktopManager.gnome.extraGSettingsOverridePackages" />.
    </para>
    <para>
      You can use <literal>dconf-editor</literal> tool to explore which
      GSettings you can set.
    </para>
    <section xml:id="sec-gnome-gsettings-overrides-example">
      <title>Example</title>
      <programlisting>
services.xserver.desktopManager.gnome = {
  extraGSettingsOverrides = ''
    # Change default background
    [org.gnome.desktop.background]
    picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue.gnomeFilePath}'

    # 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.gnome.gnome-shell # for org.gnome.shell
  ];
};
</programlisting>
    </section>
  </section>
  <section xml:id="sec-gnome-faq">
    <title>Frequently Asked Questions</title>
    <section xml:id="sec-gnome-faq-can-i-use-lightdm-with-gnome">
      <title>Can I use LightDM with GNOME?</title>
      <para>
        Yes you can, and any other display-manager in NixOS.
      </para>
      <para>
        However, it doesn’t work correctly for the Wayland session of
        GNOME Shell yet, and won’t be able to lock your screen.
      </para>
      <para>
        See
        <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56342">this
        issue.</link>
      </para>
    </section>
  </section>
</chapter>