diff --git a/pkgs/stdenv/adapters.nix b/pkgs/stdenv/adapters.nix
index 34198cff65d9..0c3b7ba7e979 100644
--- a/pkgs/stdenv/adapters.nix
+++ b/pkgs/stdenv/adapters.nix
@@ -420,15 +420,7 @@ rec {
       });
     });
 
-  # Overriding the SDK changes the Darwin SDK used to build the package, which:
-  # * Ensures that the compiler and bintools have the correct Libsystem version; and
-  # * Replaces any SDK references with those in the SDK corresponding to the requested SDK version.
-  #
-  # `sdkVersion` can be any of the following:
-  # * A version string indicating the requested SDK version; or
-  # * An attrset consisting of either or both of the following fields: darwinSdkVersion and darwinMinVersion.
-  #
-  # Note: `overrideSDK` is deprecated. Add the versioned variants of `apple-sdk` to `buildInputs` change the SDK.
+  # `overrideSDK` is deprecated. Add the versioned variants of `apple-sdk` to `buildInputs` change the SDK.
   overrideSDK = pkgs.callPackage ./darwin/override-sdk.nix { inherit lib extendMkDerivationArgs; };
 
   withDefaultHardeningFlags =
diff --git a/pkgs/stdenv/darwin/override-sdk.nix b/pkgs/stdenv/darwin/override-sdk.nix
index 482c11ce0cb2..ce4d48874b0c 100644
--- a/pkgs/stdenv/darwin/override-sdk.nix
+++ b/pkgs/stdenv/darwin/override-sdk.nix
@@ -1,5 +1,5 @@
 # This is a compatibility shim with `overrideSDK`.
-# Note: `overrideSDK` is deprecated. It will be added to `aliases.nix` after in-tree usage has been cleaned up.
+# Note: `overrideSDK` is deprecated. It will be removed in 25.11.
 {
   lib,
   stdenvNoCC,
@@ -19,6 +19,9 @@ assert lib.assertMsg (darwinSdkVersion == "11.0" || darwinSdkVersion == "12.3")
 
   See the stdenv documentation for how to use `apple-sdk`.
 '';
+assert lib.warn
+  "overrideSDK: this mechanism is deprecated and will be removed in 25.11, use `apple-sdk_*` or `darwinMinVersionHook` in build inputs instead; see <https://nixos.org/manual/nixpkgs/stable/#sec-darwin> for documentation"
+  true;
 stdenv.override (old: {
   mkDerivationFromStdenv = extendMkDerivationArgs old (args: {
     buildInputs =