diff --git a/lib/keymap-helpers.nix b/lib/keymap-helpers.nix
index a7d0451c..bc97e541 100644
--- a/lib/keymap-helpers.nix
+++ b/lib/keymap-helpers.nix
@@ -106,8 +106,12 @@ rec {
             description = ''
               If true, `action` is considered to be lua code.
               Thus, it will not be wrapped in `""`.
+
+              This option is deprecated and will be removed in 24.11.
+              You should use a "raw" action instead, e.g. `action.__raw = ""`.
             '';
             default = defaults.lua or false;
+            visible = false;
           };
 
           options = mapConfigOptions;
diff --git a/modules/keymaps.nix b/modules/keymaps.nix
index 65bc8f8d..bc4db7a6 100644
--- a/modules/keymaps.nix
+++ b/modules/keymaps.nix
@@ -2,6 +2,7 @@
   lib,
   helpers,
   config,
+  options,
   ...
 }:
 with lib;
@@ -26,13 +27,11 @@ with lib;
         "InsertEnter" = [
           {
             key = "<C-y>";
-            action = ''require("cmp").mapping.confirm()'';
-            lua = true;
+            action.__raw = ''require("cmp").mapping.confirm()'';
           }
           {
             key = "<C-n>";
-            action = ''require("cmp").mapping.select_next_item()'';
-            lua = true;
+            action.__raw = ''require("cmp").mapping.select_next_item()'';
           }
         ];
       };
@@ -52,6 +51,36 @@ with lib;
       };
     in
     {
+      # Deprecate `lua` keymap option
+      # TODO upgrade to an assertion (removal notice) in 24.11
+      # TODO remove entirely in 25.05?
+      warnings =
+        let
+          luaDefs = pipe options.keymaps.definitionsWithLocations [
+            (map (def: {
+              inherit (def) file;
+              value = filter (hasAttr "lua") def.value;
+            }))
+            (filter (def: def.value != [ ]))
+            (map (
+              def:
+              let
+                count = length def.value;
+                plural = count > 1;
+              in
+              "Found ${toString count} use${optionalString plural "s"} in ${def.file}"
+            ))
+          ];
+        in
+        optional (luaDefs != [ ]) ''
+          Nixvim (keymaps): the `lua` keymap option is deprecated.
+
+          This option will be removed in 24.11. You should use a "raw" `action` instead;
+          e.g. `action.__raw = "<lua code>"` or `action = helpers.mkRaw "<lua code>"`.
+
+          ${concatStringsSep "\n" luaDefs}
+        '';
+
       extraConfigLua = optionalString (config.keymaps != [ ]) ''
         -- Set up keybinds {{{
         do