-*usr_52.txt* For Vim version 9.2. Last change: 2026 Feb 14
+*usr_52.txt* For Vim version 9.2. Last change: 2026 Jul 27
VIM USER MANUAL by Bram Moolenaar
==============================================================================
*52.2* Autoloading
-After splitting your large script into pieces, all the lines will still be
-loaded and executed the moment the script is used. Every `import` loads the
-imported script to find the items defined there. Although that is good for
-finding errors early, it also takes time. Which is wasted if the
-functionality is not often used.
+After splitting a large script into pieces, an imported script is loaded and
+executed at the moment the importing script is sourced. Every |:import| loads
+the imported script to find the items defined there. However, if an imported
+script is large, then the startup time may become noticeably slower, but on
+the other hand if there are errors they will be detected at import time.
-Instead of having `import` load the script immediately, it can be postponed
-until needed. Using the example above, only one change needs to be made in
-the plugin/theplugin.vim script: >
+To avoid long startup times, the loading of an imported script may be deferred
+until it is actually needed. This is done with the `autoload` keyword. Using
+the example above, only one change is needed in `plugin/theplugin.vim`:
+>
import autoload "../lib/getmessage.vim"
-
+<
Nothing in the rest of the script needs to change. However, the types will
-not be checked. Not even the existence of the GetMessage() function is
-checked until it is used. You will have to decide what is more important for
-your script: fast startup or getting errors early. You can also add the
-"autoload" argument later, after you have checked everything works.
+not be checked, and "../lib/getmessage.vim" is not loaded at import time; Vim
+only verifies that the file exists and is readable. Not even the existence of
+the GetMessage() function is checked until it is used. As a result, errors in
+the "getmessage.vim" script are detected only at runtime.
+You will have to decide what is more important for your script: fast startup
+or getting errors early.
-AUTOLOAD DIRECTORY
+A practical strategy is to omit the `autoload` keyword during development and
+debugging so that errors are reported immediately, then add it back before
+distributing your plugin to improve startup performance.
-Another form is to use autoload with a script name that is not an absolute or
-relative path: >
- import autoload "monthlib.vim"
-This will search for the script "monthlib.vim" in the autoload directories of
-'runtimepath'. With Unix one of the directories often is "~/.vim/autoload".
-It will also search under 'packpath', under "start".
+AUTOLOAD DIRECTORIES
-The main advantage of this is that this script can be easily shared with other
-scripts. You do need to make sure that the script name is unique, since Vim
-will search all the "autoload" directories in 'runtimepath', and if you are
-using several plugins with a plugin manager, it may add a directory to
-'runtimepath', each of which might have an "autoload" directory.
+Another way to lazily load scripts is to `import autoload` a script without
+specifying any relative or absolute path, like in the following example: >
-Without autoload: >
+ import autoload "monthlib.vim"
+<
+Vim searches for the script in the "autoload" directories under 'runtimepath'.
+This means that the script must reside in an "autoload" folder. On Unix
+systems, one such directory is often `~/.vim/autoload`. It will also search
+under 'packpath', under "start".
+
+When a script is imported this way, its exported symbols are referenced
+through a global autoload namespace rather than remaining local to the
+importing script.
+
+Since Vim searches every "autoload" directory in 'runtimepath', choose a
+unique script name. Plugin managers often add multiple directories to
+'runtimepath', each of which may contain an "autoload" directory.
+
+The two forms of `import autoload` are summarized as follows:
+
+- `import autoload "foo.vim"`
+ Vim searches 'runtimepath' for the script. Because such scripts must reside
+ under an "autoload" directory, exported symbols are available through the
+ global autoload namespace.
+
+- `import autoload "/some/path/foo.vim"`
+ If the resolved path falls under an "autoload" directory, exported symbols
+ are likewise in the global autoload namespace; otherwise they remain local
+ to the importing script.
+
+The main advantage of accessing symbols through the global autoload namespace
+is that the script can be easily imported by other scripts, and symbols can
+be used straight away. However, this has some drawbacks when reloading a
+script, see |vim9-reload| for more info.
+
+When symbols are in script-local scope, sharing them across scripts is more
+involved and there is no general rule: the right approach depends on the
+plugin layout.
+
+Finally, when a script is imported without `autoload` and without path, like
+the following example: >
import "monthlib.vim"
-
+<
Vim will search for the script "monthlib.vim" in the import directories of
-'runtimepath'. Note that in this case adding or removing "autoload" changes
-where the script is found. With a relative or absolute path the location does
-not change.
+'runtimepath'.
+
+In this case, adding or removing the `autoload` keyword changes where Vim
+searches for the script. When a relative or absolute path is used, then the
+location does not change.
==============================================================================
*52.3* Autoloading without import/export
projects / thirdparty / vim.git / commitdiff
