From f83867d2d443a254b44223b1fa2b043f5e1b3b2f Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Tue, 20 Jan 2026 23:17:19 +0800
Subject: [PATCH 1/2] buildPythonPackage: comment on
 passthru.__stdenvPythonCompat

---
 pkgs/development/interpreters/python/mk-python-derivation.nix | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pkgs/development/interpreters/python/mk-python-derivation.nix b/pkgs/development/interpreters/python/mk-python-derivation.nix
index 0fb0a1326025c..771d0050bc843 100644
--- a/pkgs/development/interpreters/python/mk-python-derivation.nix
+++ b/pkgs/development/interpreters/python/mk-python-derivation.nix
@@ -418,6 +418,9 @@ lib.extendMkDerivation {
           optional-dependencies
           ;
         updateScript = nix-update-script { };
+        # __stdenvPythonCompat attribute is here for overrideStdenvCompat in `python-packages-base.nix` to work.
+        # It is internal and subject to changes.
+        # TODO(@ShamrockLee): Remove when overrideStdenvCompat gets removed.
         ${if attrs ? stdenv then "__stdenvPythonCompat" else null} = attrs.stdenv;
       }
       // attrs.passthru or { };

From 773f5cc8c8e18127258a5eafcd1875f369fb7862 Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Tue, 20 Jan 2026 23:13:13 +0800
Subject: [PATCH 2/2] buildPythonPackage: overrideStdenvCompat: add position to
 warning message

Co-authored-by: Matt Sturgeon <matt@sturgeon.me.uk>
---
 .../python/mk-python-derivation.nix           |  6 +++--
 .../python/python-packages-base.nix           | 27 +++++++++++--------
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/pkgs/development/interpreters/python/mk-python-derivation.nix b/pkgs/development/interpreters/python/mk-python-derivation.nix
index 771d0050bc843..74664cd5cd37d 100644
--- a/pkgs/development/interpreters/python/mk-python-derivation.nix
+++ b/pkgs/development/interpreters/python/mk-python-derivation.nix
@@ -418,10 +418,12 @@ lib.extendMkDerivation {
           optional-dependencies
           ;
         updateScript = nix-update-script { };
-        # __stdenvPythonCompat attribute is here for overrideStdenvCompat in `python-packages-base.nix` to work.
-        # It is internal and subject to changes.
+        # __stdenvPythonCompat[Pos] attributes are here for overrideStdenvCompat in `python-packages-base.nix` to work.
+        # They are internal and subject to changes.
         # TODO(@ShamrockLee): Remove when overrideStdenvCompat gets removed.
         ${if attrs ? stdenv then "__stdenvPythonCompat" else null} = attrs.stdenv;
+        ${if attrs ? stdenv then "__stdenvPythonCompatPos" else null} =
+          builtins.unsafeGetAttrPos "stdenv" attrs;
       }
       // attrs.passthru or { };
 
diff --git a/pkgs/development/interpreters/python/python-packages-base.nix b/pkgs/development/interpreters/python/python-packages-base.nix
index 77ac266301610..58a7480029b44 100644
--- a/pkgs/development/interpreters/python/python-packages-base.nix
+++ b/pkgs/development/interpreters/python/python-packages-base.nix
@@ -55,24 +55,29 @@ let
         args:
         let
           result = f args;
-          getName = x: x.pname or (lib.getName (x.name or "<unnamed>"));
-          applyMsgStdenvArg =
-            name:
-            lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) ''
-              ${name}: Passing `stdenv` directly to `buildPythonPackage` or `buildPythonApplication` is deprecated. You should use their `.override` function instead, e.g:
-                buildPythonPackage.override { stdenv = customStdenv; } { }
-            '';
+          handleStdenvArg =
+            attrs: attrName:
+            let
+              name = attrs.pname or (lib.getName (attrs.name or "<unnamed>"));
+              pos = attrs.__stdenvPythonCompatPos or (builtins.unsafeGetAttrPos attrName attrs);
+              msg = [
+                "${name}: Passing `stdenv` directly to `buildPythonPackage` or `buildPythonApplication` is deprecated. You should use their `.override` function instead, e.g:"
+                "  buildPythonPackage.override { stdenv = customStdenv; } { }"
+              ]
+              ++ lib.optionals (pos != null) [
+                "`stdenv` argument found at ${pos.file}:${toString pos.line}"
+              ];
+            in
+            lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) (lib.concatLines msg) attrs.${attrName};
         in
         if lib.isFunction args && result ? __stdenvPythonCompat then
           # Less reliable, as constructing with the wrong `stdenv` might lead to evaluation errors in the package definition.
-          f'.override { stdenv = applyMsgStdenvArg (getName result) result.__stdenvPythonCompat; } (
+          f'.override { stdenv = handleStdenvArg result "__stdenvPythonCompat"; } (
             finalAttrs: removeAttrs (args finalAttrs) [ "stdenv" ]
           )
         else if (!lib.isFunction args) && (args ? stdenv) then
           # More reliable, but only works when args is not `(finalAttrs: { })`
-          f'.override { stdenv = applyMsgStdenvArg (getName args) args.stdenv; } (
-            removeAttrs args [ "stdenv" ]
-          )
+          f'.override { stdenv = handleStdenvArg args "stdenv"; } (removeAttrs args [ "stdenv" ])
         else
           result
       )