From ab8e4b2b5ab14df0fce5510092b6497194b7b247 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Tue, 2 Dec 2025 04:33:03 +0000
Subject: [PATCH] home-environment: extend release check to include pkgs

`lib` comes from the Nixpkgs used to instantiate Home Manager itself and
cannot change within the module fixpoint. However, `pkgs` is configurable
(via `nixpkgs.*` or `_module.args`) and may come from a different Nixpkgs
instance from the one providing `lib`.

Mismatches between Home Manager's release and the release of the `pkgs`
instance are more common and also more likely to cause subtle issues.

This change extends the release check to include `pkgs.lib.trivial.release`
so that such mismatches can be detected and reported.
---
 modules/home-environment.nix                  | 21 +++++++---
 tests/modules/home-environment/default.nix    |  1 +
 .../nixpkgs-release-check-pkgs.nix            | 39 +++++++++++++++++++
 3 files changed, 56 insertions(+), 5 deletions(-)
 create mode 100644 tests/modules/home-environment/nixpkgs-release-check-pkgs.nix

diff --git a/modules/home-environment.nix b/modules/home-environment.nix
index a562047b0..602383608 100644
--- a/modules/home-environment.nix
+++ b/modules/home-environment.nix
@@ -570,14 +570,25 @@ in
     warnings =
       let
         hmRelease = config.home.version.release;
-        nixpkgsRelease = lib.trivial.release;
-        releaseMismatch = config.home.enableNixpkgsReleaseCheck && hmRelease != nixpkgsRelease;
+        libRelease = lib.trivial.release;
+        pkgsRelease = pkgs.lib.trivial.release;
+        releaseMismatch = hmRelease != libRelease || hmRelease != pkgsRelease;
+
+        versionsSummary =
+          if libRelease == pkgsRelease then
+            ''
+              Home Manager version ${hmRelease} and
+              Nixpkgs version ${libRelease}.''
+          else
+            ''
+              Home Manager version: ${hmRelease}
+              Nixpkgs version used to evaluate Home Manager: ${libRelease}
+              Nixpkgs version used for packages (`pkgs`): ${pkgsRelease}'';
       in
-      lib.optional releaseMismatch ''
+      lib.optional (config.home.enableNixpkgsReleaseCheck && releaseMismatch) ''
         You are using
 
-          Home Manager version ${hmRelease} and
-          Nixpkgs version ${nixpkgsRelease}.
+          ${lib.replaceString "\n" "\n  " versionsSummary}
 
         Using mismatched versions is likely to cause errors and unexpected
         behavior. It is therefore highly recommended to use a release of Home
diff --git a/tests/modules/home-environment/default.nix b/tests/modules/home-environment/default.nix
index c38ad5ce5..778982a30 100644
--- a/tests/modules/home-environment/default.nix
+++ b/tests/modules/home-environment/default.nix
@@ -2,4 +2,5 @@
   home-session-path = ./session-path.nix;
   home-session-search-variables = ./session-search-variables.nix;
   home-session-variables = ./session-variables.nix;
+  home-nixpkgs-release-check-pkgs = ./nixpkgs-release-check-pkgs.nix;
 }
diff --git a/tests/modules/home-environment/nixpkgs-release-check-pkgs.nix b/tests/modules/home-environment/nixpkgs-release-check-pkgs.nix
new file mode 100644
index 000000000..d0ad01c51
--- /dev/null
+++ b/tests/modules/home-environment/nixpkgs-release-check-pkgs.nix
@@ -0,0 +1,39 @@
+{ lib, ... }:
+let
+  releaseInfo = lib.importJSON ../../../release.json;
+  hmRelease = releaseInfo.release;
+  pkgsRelease = "<invalid>";
+in
+{
+  test.asserts.warnings.expected = [
+    ''
+      You are using
+
+        Home Manager version: ${hmRelease}
+        Nixpkgs version used to evaluate Home Manager: ${hmRelease}
+        Nixpkgs version used for packages (`pkgs`): ${pkgsRelease}
+
+      Using mismatched versions is likely to cause errors and unexpected
+      behavior. It is therefore highly recommended to use a release of Home
+      Manager that corresponds with your chosen release of Nixpkgs.
+
+      If you insist then you can disable this warning by adding
+
+        home.enableNixpkgsReleaseCheck = false;
+
+      to your configuration.
+    ''
+  ];
+
+  nixpkgs.overlays = [
+    (final: prev: {
+      lib = prev.lib.extend (
+        final: prev: {
+          trivial = prev.trivial // {
+            release = pkgsRelease;
+          };
+        }
+      );
+    })
+  ];
+}