Verification scope: nixpkgs
nixos-unstablemodules and upstream documentation consulted in October 2026. Group lists, package counts, and service defaults change with each revision. For deployment, use the nixpkgs and Home Manager source locked by your project as the authority. No builds, activation, or desktop runtime tests were performed for this article.
Authoritative module sources: nixos/modules/services/desktop-managers/gnome.nix (the main module) and nixos/modules/services/desktops/gnome/*.nix (service switches). The accompanying official gnome.md documentation is in the same directory as the main module. This reference lists the main public interfaces under services.desktopManager.gnome.*, services.gnome.*, and environment.gnome.*, together with the service switches available at the time and their defaults. “Automatically enabled by GNOME” indicates the service switch's actual effective default; changing it manually may break the desktop.
1. Entry Point and Desktop Manager Options: services.desktopManager.gnome.*#
| Option | Type | Default | Purpose |
|---|---|---|---|
enable |
bool | false | Enable the GNOME desktop manager; GDM is recommended but must be enabled separately |
sessionPath |
listOf package | [] |
Packages added to the session search path, for Shell extensions and GSettings-conditional autostart. The official note calls this a last resort; prefer patching where possible |
favoriteAppsOverride |
lines | Built-in default dock | Set the default for org.gnome.shell.favorite-apps. An internal option marked as messy; NixOS does not promise stability |
extraGSettingsOverrides |
lines | "" |
Additional GSettings vendor overrides (INI format: [schema] and key=value) |
extraGSettingsOverridePackages |
listOf path | [] |
Packages providing the overridden schemas, such as pkgs.gsettings-desktop-schemas and pkgs.gnome-shell |
debug |
bool | false | Enable gnome-session debug messages by setting GNOME_SESSION_DEBUG=1 |
flashback.enableMetacity |
bool | false | Standard GNOME Flashback session using the Metacity window manager |
flashback.customSessions |
listOf submodule | [] |
Custom Flashback sessions that replace Metacity with another WM |
flashback.panelModulePackages |
listOf package | [ pkgs.gnome-applets ] |
Module packages for gnome-panel, usually installed under $out/lib/gnome-panel/modules |
Each flashback.customSessions entry is a submodule with four fields:
| Field | Type | Default | Description |
|---|---|---|---|
wmName |
str([a-zA-Z0-9_-]+) |
Required | Unique identifier for the WM |
wmLabel |
str | Required | Name shown in the session selector |
wmCommand |
str | Required | Path to the WM executable |
enableGnomePanel |
bool | true | Whether to enable the GNOME panel for this session |
How extraGSettingsOverrides Works The main module combines
extraGSettingsOverrides,extraGSettingsOverridePackages, andfavoriteAppsOverrideinto thepkgs.gnome.nixos-gsettings-overridespackage, generatesshare/gsettings-schemas/nixos-gsettings-overrides/glib-2.0/schemas/, and injects it into the session through theNIX_GSETTINGS_OVERRIDES_DIRenvironment variable. This is therefore the “system defaults” layer; existing user dconf values take precedence. See Managing GSettings and dconf on NixOS.
2. Group Switches: services.gnome.* (5)#
| Switch | Effective Default | What It Controls |
|---|---|---|
core-os-services.enable |
Forced to true when GNOME is enabled | Service foundation: dconf, polkit, accounts-daemon, NetworkManager, power-profiles-daemon, xdg portal, Bluetooth, input methods (ibus by default), and more |
core-shell.enable |
Forced to true when GNOME is enabled | GNOME Shell itself and accompanying services (colord, geoclue, gvfs, the GNOME settings daemon, and more) |
core-apps.enable |
true(mkDefault) |
Full application suite (nautilus, epiphany, gnome-console, text-editor, maps, and more) |
games.enable |
false | Games (aisleriot, gnome-chess, gnome-mines, and more) |
core-developer-tools.enable |
false | Developer tools (gnome-builder, dconf-editor, devhelp, d-spy, sysprof) |
Default Structure of the Group Switches
core-os-servicesandcore-shellare assigned true at normal priority, inside the main module'slib.mkIfwith a direct= trueassignment. Disabling them dismantles the desktop.core-appsusesmkDefault true, which users can override with= falsefor a minimal GNOME setup. games/dev-tools default to false and are installed only when enabled. See Declarative GNOME Management.
3. Service Switches: services.gnome.* (16, with Modules in services/desktops/gnome/)#
Most have only a single boolean enable option; additional options are noted where present. The default column shows the effective default, including services automatically enabled by GNOME groups.
| Service | Default | Purpose |
|---|---|---|
at-spi2-core |
Automatically true with GNOME | Accessibility bus (org.a11y.Bus). Enable it if you see The name org.a11y.Bus was not provided by any .service files |
evolution-data-server |
Automatically true with GNOME | Contact/calendar data service. Additional option: plugins (listOf package, default []) |
gcr-ssh-agent |
Enabled with mkDefault by GNOME core-os-services; check the standalone module's default separately | GCR SSH agent (SSH key management) |
glib-networking |
Automatically true with GNOME | GLib networking extensions (TLS, proxies, and more) |
gnome-browser-connector |
Automatically true with GNOME | Native host for the browser extension, allowing the browser to install GNOME Shell extensions |
gnome-initial-setup |
Automatically true with GNOME | Initial setup wizard |
gnome-keyring |
Automatically true with GNOME | Keyring daemon (login credentials) |
gnome-online-accounts |
Automatically true with GNOME | Single sign-on framework |
gnome-remote-desktop |
Automatically true with GNOME | PipeWire-based remote desktop |
gnome-settings-daemon |
Automatically true with GNOME | Settings daemon (a core dependency of core-shell) |
gnome-software |
Installed only when flatpak is enabled | Software center (PackageKit does not support Nix; flatpak is required) |
gnome-user-share |
Automatically true with GNOME | User-level file sharing (WebDAV) |
localsearch |
Automatically true with GNOME | LocalSearch indexing service (a TinySPARQL frontend required by GNOME Music) |
rygel |
Automatically true with GNOME | UPnP media server. Additional option: package (default pkgs.rygel) |
sushi |
Automatically true with GNOME | Quick previewer for nautilus |
tinysparql |
Automatically true with GNOME | TinySPARQL search engine/metadata store |
Disabling Services Removes Functionality The official documentation explicitly states that disabling these services is unsupported and may break applications. A classic example: disabling both
tinysparqlandlocalsearchremoves GNOME search; GNOME Music will not work without TinySPARQL.Removed:
gnome-online-miners(mkRemovedOptionModule, broken for a while now).
4. Package Exclusion: environment.gnome.excludePackages#
environment.gnome.excludePackages = [ pkgs.epiphany ]; # 从默认 GNOME 环境剔除- Type:
listOf package, default:[]. Matches by package name to remove packages fromenvironment.systemPackagesin core-apps / games / core-developer-tools (the main module'sremoveExcluded/notExcluded) - Primarily intended to exclude packages from these three groups; the actual source also filters core-shell's optionalPackages. Most core-shell packages are mandatory; only optionalPackages can be excluded. Excluding Epiphany usually also removes the large webkitgtk package from the system closure
- Excluding a package also skips the corresponding program module. For example, excluding
sushiprevents the sushi service from being enabled; excludinggnome-disk-utilitypreventsprograms.gnome-disksfrom being enabled
5. What Each Group Installs by Default#
core-apps (25): baobab, decibels, epiphany, gnome-text-editor, gnome-calculator, gnome-calendar, gnome-characters, gnome-clocks, gnome-console, gnome-contacts, gnome-font-viewer, gnome-logs, gnome-maps, gnome-music, gnome-system-monitor, gnome-tecla, gnome-weather, loupe, nautilus, papers, gnome-connections, showtime, simple-scan, snapshot, yelp.
games (20): aisleriot, atomix, five-or-more, four-in-a-row, gnome-2048, gnome-chess, gnome-klotski, gnome-mahjongg, gnome-mines, gnome-nibbles, gnome-robots, gnome-sudoku, gnome-taquin, gnome-tetravex, hitori, iagno, lightsoff, quadrapassel, swell-foop, tali.
core-developer-tools (5): dconf-editor, devhelp, d-spy, gnome-builder, sysprof.
Some excludable optional packages in core-shell (consult your locked source): adwaita-icon-theme, gnome-backgrounds, gnome-bluetooth, gnome-color-manager, gnome-control-center, gnome-tour, gnome-user-docs, gnome-menus, xdg-user-dirs, xdg-user-dirs-gtk.
Adding Packages vs. Removing Packages To install more GNOME ecosystem packages, such as
pkgs.gpasteorpkgs.gnomeExtensions.*, add them directly toenvironment.systemPackages. To install fewer, useexcludePackages. NixOS has no dedicated option to “add custom packages through GNOME”: the group lists are hardcoded, so custom additions go through systemPackages.
Related#
- Declarative GNOME Management — practical use of the five group switches, with configuration examples
- Managing GSettings and dconf on NixOS — the three precedence layers for extraGSettingsOverrides
- GNOME Configuration on NixOS: Export Diffs, Find Keys, and Install Extensions — installing extensions and finding package names
References & further reading
Adapted from technical notes. Examples use generic names.