qt: stop rewriting platformTheme name gtk to gtk2

Setting `qt.platformTheme.name = "gtk"` silently rewrote the
QT_QPA_PLATFORMTHEME session variable to `gtk2` and pulled in the
qtstyleplugins and qt6gtk2 packages, which is not what users asked for
and relies on unmaintained packages. There is no `gtk` Qt platform
theme, so `gtk` now maps to Qt's built-in `gtk3` platform-theme plugin
and installs no extra packages.

Users who want the previous behavior can set
`qt.platformTheme.name = "gtk2"` explicitly, which keeps
QT_QPA_PLATFORMTHEME=gtk2 and installs qtstyleplugins and qt6gtk2. The
`qt.useGtkTheme` -> `qt.platformTheme` migration now maps the legacy
option to `{ name = "gtk2"; }` so existing configs are unaffected.

Fixes #8663

modules/misc/news/2026/06/2026-06-10_15-35-30.nix

@@ -0,0 +1,17 @@
+{ config, ... }:
+{
+  time = "2026-06-10T15:35:30+00:00";
+  condition = config.qt.enable;
+  message = ''
+    The value `gtk` for `qt.platformTheme.name` is no longer rewritten to
+    `gtk2` when setting the `QT_QPA_PLATFORMTHEME` session variable. It is
+    now emitted as `gtk3`, selecting Qt's built-in GTK platform theme plugin,
+    and no longer installs the `qtstyleplugins` and `qt6gtk2`
+    packages.
+
+    If you relied on the previous behavior, set
+    `qt.platformTheme.name = "gtk2"` explicitly, which sets
+    `QT_QPA_PLATFORMTHEME=gtk2` and installs the `qtstyleplugins` and
+    `qt6gtk2` packages providing that platform theme.
+  '';
+}

modules/misc/qt/default.nix

@@ -22,7 +22,7 @@ let
       qadwaitadecorations
       qadwaitadecorations-qt6
     ];
-    gtk = [
+    gtk2 = [
       libsForQt5.qtstyleplugins
       qt6Packages.qt6gtk2
     ];
@@ -41,9 +41,9 @@ let
     ];
   };
 
-  # Maps style names to their QT_QPA_PLATFORMTHEME, if necessary.
+  # Maps platform theme names to their QT_QPA_PLATFORMTHEME, if necessary.
   styleNames = {
-    gtk = "gtk2";
+    gtk = "gtk3";
     qtct = "qt5ct";
   };
 
@@ -99,7 +99,13 @@ in
     ./kvantum.nix
 
     (lib.mkChangedOptionModule [ "qt" "useGtkTheme" ] [ "qt" "platformTheme" ] (
-      config: if lib.getAttrFromPath [ "qt" "useGtkTheme" ] config then "gtk" else null
+      config:
+      if lib.getAttrFromPath [ "qt" "useGtkTheme" ] config then
+        {
+          name = "gtk2";
+        }
+      else
+        null
     ))
   ];
 
@@ -166,8 +172,12 @@ in
                 Some examples are
 
                 `gtk`
-                : Use GTK theme with
+                : Use Qt's [GTK platform theme plugin](https://github.com/qt/qtbase/tree/dev/src/plugins/platformthemes/gtk3)
+
+                `gtk2`
+                : Use GTK2 theme with
                   [`qtstyleplugins`](https://github.com/qt/qtstyleplugins)
+                  and [`qt6gtk2`](https://github.com/trialuser02/qt6gtk2)
 
                 `gtk3`
                 : Use [GTK3 integration](https://github.com/qt/qtbase/tree/dev/src/plugins/platformthemes/gtk3)
@@ -411,7 +421,10 @@ in
             old = ''"kde6"'';
             replacement = ''"kde"'';
           }
-        ));
+        ))
+        ++ (lib.lists.optional (platformTheme.name == "gtk")
+          "The value `gtk` for option `${platformTheme.option}` is deprecated. Use `gtk2` to keep the legacy qtstyleplugins or `gtk3` to use the modern native Qt GTK3 plugin."
+        );
 
       qt.style.package = lib.mkIf (cfg.style.name != null) (
         lib.mkDefault (stylePackages.${lib.toLower cfg.style.name} or null)

tests/modules/misc/qt/default.nix

@@ -3,10 +3,12 @@
   qt-kvantum-settings = ./qt-kvantum-settings.nix;
   qt-kvantum-themes = ./qt-kvantum-themes.nix;
   qt-platform-theme-gtk = ./qt-platform-theme-gtk.nix;
+  qt-platform-theme-gtk2 = ./qt-platform-theme-gtk2.nix;
   qt-platform-theme-gtk3 = ./qt-platform-theme-gtk3.nix;
   qt-platform-theme-gnome = ./qt-platform-theme-gnome.nix;
   qt-platform-theme-kde6-migration = ./qt-platform-theme-kde6-migration.nix;
   qt-qt5ct-settings = ./qt-qt5ct-settings.nix;
   qt-qt6ct-settings = ./qt-qt6ct-settings.nix;
   qt-qtct-settings = ./qt-qtct-settings.nix;
+  qt-use-gtk-theme-migration = ./qt-use-gtk-theme-migration.nix;
 }

tests/modules/misc/qt/qt-platform-theme-gtk.nix

@@ -1,5 +1,3 @@
-{ config, ... }:
-
 {
   qt = {
     enable = true;
@@ -11,25 +9,13 @@
     type = "fcitx5";
   };
 
-  nixpkgs.overlays = [
-    (_final: prev: {
-      libsForQt5 = prev.libsForQt5.overrideScope (
-        _qt5final: _qt5prev: {
-          qtstyleplugins = config.lib.test.mkStubPackage { outPath = null; };
-        }
-      );
-
-      qt6Packages = prev.qt6Packages.overrideScope (
-        _qt6final: _qt6prev: {
-          qt6gtk2 = config.lib.test.mkStubPackage { outPath = null; };
-        }
-      );
-    })
+  test.asserts.warnings.expected = [
+    "The value `gtk` for option `qt.platformTheme.name` is deprecated. Use `gtk2` to keep the legacy qtstyleplugins or `gtk3` to use the modern native Qt GTK3 plugin."
   ];
 
   nmt.script = ''
     assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \
-      'QT_QPA_PLATFORMTHEME="gtk2"'
+      'QT_QPA_PLATFORMTHEME="gtk3"'
     assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \
       'QT_PLUGIN_PATH'
     assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \

tests/modules/misc/qt/qt-platform-theme-gtk2.nix

@@ -0,0 +1,43 @@
+{ config, ... }:
+
+{
+  qt = {
+    enable = true;
+    platformTheme.name = "gtk2";
+  };
+
+  nixpkgs.overlays = [
+    (_final: prev: {
+      libsForQt5 = prev.libsForQt5.overrideScope (
+        _qt5final: _qt5prev: {
+          qtstyleplugins = config.lib.test.mkStubPackage {
+            name = "qtstyleplugins";
+            buildScript = ''
+              mkdir -p $out/share
+              touch $out/share/qtstyleplugins
+            '';
+          };
+        }
+      );
+
+      qt6Packages = prev.qt6Packages.overrideScope (
+        _qt6final: _qt6prev: {
+          qt6gtk2 = config.lib.test.mkStubPackage {
+            name = "qt6gtk2";
+            buildScript = ''
+              mkdir -p $out/share
+              touch $out/share/qt6gtk2
+            '';
+          };
+        }
+      );
+    })
+  ];
+
+  nmt.script = ''
+    assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \
+      'QT_QPA_PLATFORMTHEME="gtk2"'
+    assertFileExists home-path/share/qtstyleplugins
+    assertFileExists home-path/share/qt6gtk2
+  '';
+}

tests/modules/misc/qt/qt-use-gtk-theme-migration.nix

@@ -0,0 +1,52 @@
+{
+  config,
+  lib,
+  options,
+  ...
+}:
+
+{
+  qt = {
+    enable = true;
+    useGtkTheme = true;
+  };
+
+  nixpkgs.overlays = [
+    (_final: prev: {
+      libsForQt5 = prev.libsForQt5.overrideScope (
+        _qt5final: _qt5prev: {
+          qtstyleplugins = config.lib.test.mkStubPackage {
+            name = "qtstyleplugins";
+            buildScript = ''
+              mkdir -p $out/share
+              touch $out/share/qtstyleplugins
+            '';
+          };
+        }
+      );
+
+      qt6Packages = prev.qt6Packages.overrideScope (
+        _qt6final: _qt6prev: {
+          qt6gtk2 = config.lib.test.mkStubPackage {
+            name = "qt6gtk2";
+            buildScript = ''
+              mkdir -p $out/share
+              touch $out/share/qt6gtk2
+            '';
+          };
+        }
+      );
+    })
+  ];
+
+  test.asserts.warnings.expected = [
+    "The option `qt.useGtkTheme' defined in ${lib.showFiles options.qt.useGtkTheme.files} has been changed to `qt.platformTheme' that has a different type. Please read `qt.platformTheme' documentation and update your configuration accordingly."
+  ];
+
+  nmt.script = ''
+    assertFileRegex home-path/etc/profile.d/hm-session-vars.sh \
+      'QT_QPA_PLATFORMTHEME="gtk2"'
+    assertFileExists home-path/share/qtstyleplugins
+    assertFileExists home-path/share/qt6gtk2
+  '';
+}