From settings diffs to declarations and extensions

Verification scope: nixpkgs nixos-unstable modules 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.

“I changed a lot of things in GNOME Settings. How do I keep them when I move to another machine?” The complete answer is a four-step workflow: export a diff → find the key names → write declarations → find package names/install extensions when needed. The commands below are examples for review, with the underlying mechanisms checked against nixpkgs source. They have not been verified on the target desktop.

1. Export a Configuration Diff#

The dconf database (~/.config/dconf/user) stores explicitly written user key/value pairs, not necessarily only values that differ from the defaults. Comparing two exports reveals database changes during that interval; state written by background applications at the same time will also appear in the diff:

dconf dump / > before.txt      # 改动前导出
# ……在 GNOME 设置里改几个选项……
dconf dump / > after.txt
diff before.txt after.txt      # 就是你这次改的所有设置

The Output Format Needs Conversion dconf dump produces INI-style output, but its sections are paths, such as [org/gnome/desktop/interface]. extraGSettingsOverrides uses schema IDs, such as [org.gnome.desktop.interface]. Convert between the two using the actual schema/path mapping (see Managing GSettings and dconf on NixOS). Filter out unrelated state, verify schema IDs and types, and add the packages providing the schemas before writing the result to host/gnome.nix.

To see which key changes in real time, run dconf watch /org/gnome/desktop/interface/ and change settings while it is running to capture the key paths.

2. Find the Corresponding Key Names#

The settings UI shows translated option names without revealing the underlying keys. There are three ways to find them:

gsettings list-recursively | grep -i dark        # 全局搜"值/键名"含 dark
gsettings list-keys org.gnome.desktop.interface   # 某 schema 的全部键
gsettings describe org.gnome.desktop.interface color-scheme   # 键的含义
gsettings range org.gnome.desktop.interface color-scheme      # 允许值
dconf list /org/gnome/desktop/interface/          # dconf 路径视角

• gsettings is a schema-aware API (schema.key notation); dconf is the underlying database (/org/gnome/... path notation). They read the same database.
• Cannot remember the schema name? Use gsettings list-schemas | grep -i 关键词.
• Graphical fallback: dconf-editor lets you browse and search the entire tree, showing each key's current value and type.
• At the source level, each key's definition, including its default, range, and description, is in the gsettings-desktop-schemas package's *.gschema.xml files. This is what gsettings describe reads.

3. Install Extensions#

Declarative installation is recommended for extensions on NixOS:

# host/gnome.nix（示例）
environment.systemPackages = [ pkgs.gnomeExtensions.kimpanel ];

Underlying mechanism (nixpkgs source: pkgs/desktops/gnome/extensions/):

• extensions.json is an index scraped from extensions.gnome.org. Each entry includes shell_version_map, indicating the GNOME versions supported by the extension
• default.nix filters by the current shell version → buildGnomeExtension.nix builds the extension → it is installed under $out/share/gnome-shell/extensions/<uuid>/
• pkgs.gnomeExtensions collects extensions according to nixpkgs' extension-generation and version-selection policy. Keys are readable pname values, not UUIDs
• GNOME Shell uses XDG_DATA_DIRS to scan /run/current-system/sw/share/gnome-shell/extensions/ and discover system-level extensions

Enable Extensions After Installing Them Installing into systemPackages does not enable an extension. Enable it manually in GNOME's Extensions app, or run gnome-extensions enable <uuid>. If the current Shell has not discovered a newly installed extension, you usually need to log out and back in. Compatible extensions that have already been discovered can be toggled with the enable command.

User-level alternative: manually extract the extension into ~/.local/share/gnome-shell/extensions/<uuid>/. This is not declarative: rebuild does not affect it, and it will not follow you to another machine. Avoid this route unless the extension is unavailable in nixpkgs.

4. Find the Package Name#

Finding a package name involves two questions: what is it called in the attrset, and is it in nixpkgs?

nix search nixpkgs gnomeExtensions | grep -i "<关键词>"   # 模糊搜
nix eval nixpkgs#gnomeExtensions --apply builtins.attrNames --json | jq -r '.[]' # 列出全部扩展名

• For an extension found on extensions.gnome.org, first note its UUID, such as kimpanel@kde.org. Then search by pname or UUID in the local source file pkgs/desktops/gnome/extensions/extensions.json to confirm its nixpkgs name and version directly.
• The package name and display name often differ: Forge, Pop Shell, and ArcMenu each have a specific pname. nix search is the quickest way to match them up.

From Runtime Preferences to Reusable Declarations Together, these four skills form a complete GNOME customization workflow: change a setting → capture the key in a diff → put it in extraGSettingsOverrides → use nix search gnomeExtensions to install new functionality when needed. Everything becomes reproducible, so your carefully configured desktop is no longer lost when you change machines.

Related#

• Managing GSettings and dconf on NixOS — where exported settings belong and why they are “overridable defaults”
• Declarative GNOME Management — group switches and the module layer
• NixOS Declarative and Runtime Layers — dconf is runtime state; exporting it “promotes it to the declarative layer”

Enable Extensions Declaratively#

Installing a package and enabling its UUID are separate steps. You can declare the enabled list in Home Manager:

dconf.settings."org/gnome/shell" = {
  disable-user-extensions = false;
  enabled-extensions = [ "kimpanel@kde.org" ];
};

This list is written back during activation and should include all extension UUIDs you want to retain, rather than letting each module overwrite it with its own single extension. Verify UUIDs in the installed extension's metadata.json or with gnome-extensions list. Shell-version mismatches, extension errors, and installation-path problems still require runtime checks.