modules: add minimal entrypoint to only enable core modules

docs/release-notes/rl-2511.md

@@ -48,6 +48,24 @@ This release has the following notable changes:
   to your configuration. This option is likely to be deprecated in the
   future.
 
+- By default, Home Manager imports all modules, which leads to
+  increased evaluation time. Some users may wish to only import the
+  modules they actually use. To accomodate this, a new option
+  `home-manager.minimal` has been added. When this option is enabled,
+  Home Manager will only import the basic set of modules it requires
+  to function. Other modules will have to be enabled manually, like
+  this:
+
+
+  ```nix
+    imports = [
+      "${modulesPath}/programs/fzf.nix"
+    ];
+  ```
+
+  This entrypoint is only recommended for advanced users, who are
+  comfortable maintaining a personal list of modules to import.
+
 - The use of `services.syncthing.tray` as a Boolean option was removed
   after being deprecated in 2021. You are now expected to use
   [](#opt-services.syncthing.tray.enable) to enable the Syncthing tray

lib/default.nix

@@ -9,13 +9,15 @@
       lib ? pkgs.lib,
       modules ? [ ],
       pkgs,
+      minimal ? false,
     }:
     import ../modules {
       inherit
         check
         extraSpecialArgs
         lib
         pkgs
+        minimal
         ;
       configuration =
         { ... }:

modules/misc/news/2025/10/2025-10-10_20-06-01.nix

@@ -0,0 +1,22 @@
+{
+  time = "2025-10-11T00:06:01+00:00";
+  condition = true;
+  message = ''
+    A new option is availabe: `home-manager.minimal`
+
+    By default, Home Manager imports all modules, which leads to increased
+    evaluation time. Some users may wish to only import the modules they
+    actually use. When the new option is enabled, Home Manager will only
+    import the basic set of modules it requires to function. Other modules
+    will have to be enabled manually, like this:
+
+    ```nix
+      imports = [
+        "''${modulesPath}/programs/fzf.nix"
+      ];
+    ```
+
+    This entrypoint is only recommended for advanced users, who are
+    comfortable maintaining a personal list of modules to import.
+  '';
+}

modules/modules.nix

@@ -9,85 +9,105 @@
 
   # If disabled, the pkgs attribute passed to this function is used instead.
   useNixpkgsModule ? true,
+
+  # Whether to only import the required modules, and let the user add modules
+  # manually
+  minimal ? false,
 }:
 
 let
 
-  modules = [
-    # keep-sorted start case=no numeric=yes
-    ./accounts/calendar.nix
-    ./accounts/contacts.nix
-    ./accounts/email.nix
-    ./config/home-cursor.nix
-    ./config/i18n.nix
-    ./dbus.nix
-    ./files.nix
-    ./home-environment.nix
-    ./i18n/input-method/default.nix
-    ./launchd/default.nix
-    ./manual.nix
-    ./misc/dconf.nix
-    ./misc/debug.nix
-    ./misc/editorconfig.nix
-    ./misc/fontconfig.nix
-    ./misc/gtk.nix
-    ./misc/lib.nix
-    ./misc/mozilla-messaging-hosts.nix
-    ./misc/news.nix
-    ./misc/nix-remote-build.nix
-    ./misc/nix.nix
-    ./misc/nixgl.nix
-    ./misc/numlock.nix
-    ./misc/pam.nix
-    ./misc/qt.nix
-    ./misc/qt/kconfig.nix
-    ./misc/shell.nix
-    ./misc/specialisation.nix
-    ./misc/submodule-support.nix
-    ./misc/tmpfiles.nix
-    ./misc/uninstall.nix
-    ./misc/version.nix
-    ./misc/vte.nix
-    ./misc/xdg-autostart.nix
-    ./misc/xdg-desktop-entries.nix
-    ./misc/xdg-mime-apps.nix
-    ./misc/xdg-mime.nix
-    ./misc/xdg-portal.nix
-    ./misc/xdg-system-dirs.nix
-    ./misc/xdg-terminal-exec.nix
-    ./misc/xdg-user-dirs.nix
-    ./misc/xdg.nix
-    ./misc/xfconf.nix
-    ./systemd.nix
-    ./targets/darwin
-    ./targets/generic-linux.nix
-    ./wayland.nix
-    ./xresources.nix
-    ./xsession.nix
-    # keep-sorted end
-    (pkgs.path + "/nixos/modules/misc/assertions.nix")
-    (pkgs.path + "/nixos/modules/misc/meta.nix")
-    # Module deprecations and removals
-    ./deprecations.nix
-  ]
-  ++ (lib.concatMap
-    (
-      dir:
-      lib.pipe (builtins.readDir dir) [
-        (lib.filterAttrs (path: _kind: !lib.hasPrefix "_" path))
-        (lib.filterAttrs (
-          _path: kind: kind == "directory" || (kind == "regular" && lib.hasSuffix ".nix" _path)
-        ))
-        (lib.mapAttrsToList (path: _kind: lib.path.append dir path))
-      ]
-    )
+  modules = builtins.concatLists [
     [
-      ./services
-      ./programs
+      # keep-sorted start case=no numeric=yes
+      ./accounts/calendar.nix
+      ./accounts/contacts.nix
+      ./accounts/email.nix
+      ./config/home-cursor.nix
+      ./config/i18n.nix
+      ./dbus.nix
+      ./files.nix
+      ./home-environment.nix
+      ./i18n/input-method/default.nix
+      ./launchd/default.nix
+      ./manual.nix
+      ./misc/dconf.nix
+      ./misc/debug.nix
+      ./misc/editorconfig.nix
+      ./misc/fontconfig.nix
+      ./misc/gtk.nix
+      ./misc/lib.nix
+      ./misc/mozilla-messaging-hosts.nix
+      ./misc/news.nix
+      ./misc/nix-remote-build.nix
+      ./misc/nix.nix
+      ./misc/nixgl.nix
+      ./misc/numlock.nix
+      ./misc/pam.nix
+      ./misc/qt.nix
+      ./misc/qt/kconfig.nix
+      ./misc/shell.nix
+      ./misc/specialisation.nix
+      ./misc/submodule-support.nix
+      ./misc/tmpfiles.nix
+      ./misc/uninstall.nix
+      ./misc/version.nix
+      ./misc/vte.nix
+      ./misc/xdg-autostart.nix
+      ./misc/xdg-desktop-entries.nix
+      ./misc/xdg-mime-apps.nix
+      ./misc/xdg-mime.nix
+      ./misc/xdg-portal.nix
+      ./misc/xdg-system-dirs.nix
+      ./misc/xdg-terminal-exec.nix
+      ./misc/xdg-user-dirs.nix
+      ./misc/xdg.nix
+      ./misc/xfconf.nix
+      ./systemd.nix
+      ./targets/darwin
+      ./targets/generic-linux.nix
+      ./wayland.nix
+      ./xresources.nix
+      ./xsession.nix
+      # keep-sorted end
+      (pkgs.path + "/nixos/modules/misc/assertions.nix")
+      (pkgs.path + "/nixos/modules/misc/meta.nix")
+      # Module deprecations and removals
+      ./deprecations.nix
     ]
-  )
-  ++ lib.optional useNixpkgsModule ./misc/nixpkgs.nix
-  ++ lib.optional (!useNixpkgsModule) ./misc/nixpkgs-disabled.nix;
+
+    (lib.optional useNixpkgsModule ./misc/nixpkgs.nix)
+
+    (lib.optional (!useNixpkgsModule) ./misc/nixpkgs-disabled.nix)
+
+    (
+      if minimal then
+        [
+          ./programs/bash.nix
+          ./programs/autojump.nix # Dependency of bash module
+          ./programs/zsh
+          ./programs/ion.nix
+          ./programs/nushell.nix
+          ./services/window-managers/i3-sway/default.nix # Dependency of home-cursor module
+        ]
+      else
+        lib.concatMap
+          (
+            dir:
+            lib.pipe (builtins.readDir dir) [
+              (lib.filterAttrs (path: _kind: !lib.hasPrefix "_" path))
+              (lib.filterAttrs (
+                _path: kind: kind == "directory" || (kind == "regular" && lib.hasSuffix ".nix" _path)
+              ))
+              (lib.mapAttrsToList (path: _kind: lib.path.append dir path))
+            ]
+          )
+          [
+            ./services
+            ./programs
+          ]
+    )
+  ];
 
   pkgsModule =
     { config, ... }:

nixos/common.nix

@@ -42,6 +42,7 @@ let
             import ../modules/modules.nix {
               inherit pkgs;
               lib = extendedLib;
+              minimal = cfg.minimal;
               useNixpkgsModule = !cfg.useGlobalPkgs;
             }
             ++ cfg.sharedModules;
@@ -105,6 +106,14 @@ in
       '';
     };
 
+    minimal = mkEnableOption ''
+      only the necessary modules that allow home-manager to function. This can
+      be used to allow vendoring a minimal list of modules yourself, rather than
+      importing every single module. THIS IS FOR ADVANCED USERS, AND WILL
+      DISABLE ALmOST EVERY MODULE. THIS SHOULD NOT BE ENABLED UNLESS YOU KNOW
+      THE IMPLICATIONS.
+    '';
+
     sharedModules = mkOption {
       type = with types; listOf raw;
       default = [ ];