diff --git a/pkgs/development/interpreters/python/python-packages-base.nix b/pkgs/development/interpreters/python/python-packages-base.nix
index 1c3b4d309523..19a46dc7ee74 100644
--- a/pkgs/development/interpreters/python/python-packages-base.nix
+++ b/pkgs/development/interpreters/python/python-packages-base.nix
@@ -50,8 +50,10 @@ let
     lib.setFunctionArgs (
       args:
       if !(lib.isFunction args) && (args ? stdenv) then
-        # TODO: warn that `args ? stdenv` is deprecated (once in-tree usage is migrated)
-        f.override { stdenv = args.stdenv; } args
+        lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) ''
+          Passing `stdenv` directly to `buildPythonPackage` or `buildPythonApplication` is deprecated. You should use their `.override` function instead, e.g:
+            buildPythonPackage.override { stdenv = customStdenv; } { }
+        '' (f.override { stdenv = args.stdenv; } args)
       else
         f args
     ) (removeAttrs (lib.functionArgs f) [ "stdenv" ])