diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index f92ef26399..0703b7e9d0 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3265,6 +3265,12 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
       pattern = { "*.py", "*.pyi" }
 <
 
+    Note: The `pattern` is passed to callbacks and commands as a literal string; environment
+    variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
+    |expand()| such variables explicitly: >
+      pattern = vim.fn.expand("~") .. "/some/path/*.py"
+<
+
     Example values for event: >
       "BufWritePre"
       {"CursorHold", "BufWritePre", "BufWritePost"}
@@ -3277,7 +3283,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                  • group (string|integer) optional: the autocommand group name
                    or id to match against.
                  • pattern (string|array) optional: pattern or patterns to
-                   match against |autocmd-pattern|.
+                   match literally against |autocmd-pattern|.
                  • buffer (integer) optional: buffer number for buffer local
                    autocommands |autocmd-buflocal|. Cannot be used with
                    {pattern}.
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index b5c695b9ce..3dfe77ba38 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -401,6 +401,13 @@ cleanup:
 ///   pattern = { "*.py", "*.pyi" }
 /// </pre>
 ///
+/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
+/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
+/// Instead, |expand()| such variables explicitly:
+/// <pre>
+///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// </pre>
+///
 /// Example values for event:
 /// <pre>
 ///   "BufWritePre"
@@ -411,7 +418,7 @@ cleanup:
 /// @param opts Dictionary of autocommand options:
 ///             - group (string|integer) optional: the autocommand group name or
 ///             id to match against.
-///             - pattern (string|array) optional: pattern or patterns to match
+///             - pattern (string|array) optional: pattern or patterns to match literally
 ///             against |autocmd-pattern|.
 ///             - buffer (integer) optional: buffer number for buffer local autocommands
 ///             |autocmd-buflocal|. Cannot be used with {pattern}.