diff --git a/lib/deprecation.nix b/lib/deprecation.nix
new file mode 100644
index 00000000..6cf6d57c
--- /dev/null
+++ b/lib/deprecation.nix
@@ -0,0 +1,49 @@
+{ lib, ... }:
+with lib;
+rec {
+  # Get a (sub)option by walking the path,
+  # checking for submodules along the way
+  getOptionRecursive =
+    opt: prefix: optionPath:
+    if optionPath == [ ] then
+      opt
+    else if isOption opt then
+      getOptionRecursive (opt.type.getSubOptions prefix) prefix optionPath
+    else
+      let
+        name = head optionPath;
+        opt' = getAttr name opt;
+        prefix' = prefix ++ [ name ];
+        optionPath' = drop 1 optionPath;
+      in
+      getOptionRecursive opt' prefix' optionPath';
+
+  # Like mkRemovedOptionModule, but has support for nested sub-options
+  # and uses warnings instead of assertions.
+  mkDeprecatedSubOptionModule =
+    optionPath: replacementInstructions:
+    { options, ... }:
+    {
+      options = setAttrByPath optionPath (mkOption {
+        # When (e.g.) `mkAttrs` is used on a submodule, this option will be evaluated.
+        # Therefore we have to apply _something_ (null) when there's no definition.
+        apply =
+          v:
+          let
+            # Avoid "option used but not defined" errors
+            res = builtins.tryEval v;
+          in
+          if res.success then res.value else null;
+        visible = false;
+      });
+      config.warnings =
+        let
+          opt = getOptionRecursive options [ ] optionPath;
+        in
+        optional opt.isDefined ''
+          The option definition `${showOption optionPath}' in ${showFiles opt.files} is deprecated.
+          ${replacementInstructions}
+        '';
+    };
+
+}
diff --git a/lib/helpers.nix b/lib/helpers.nix
index 0115038d..5403ba5f 100644
--- a/lib/helpers.nix
+++ b/lib/helpers.nix
@@ -9,6 +9,7 @@ let
   nixvimTypes = import ./types.nix { inherit lib nixvimOptions; };
   nixvimUtils = import ./utils.nix { inherit lib nixvimTypes _nixvimTests; };
   nixvimOptions = import ./options.nix { inherit lib nixvimTypes nixvimUtils; };
+  nixvimDeprecation = import ./deprecation.nix { inherit lib; };
   inherit (import ./to-lua.nix { inherit lib; }) toLuaObject;
 in
 {
@@ -30,3 +31,4 @@ in
 // nixvimUtils
 // nixvimOptions
 // nixvimBuilders
+// nixvimDeprecation