Base Directories

The first step to getting started with configuration is understanding how Neovim loads your configuration files.

Neovim follows the XDG Base Directory specification, which defines a group of environment variables that specify where applications load and store configuration and other information. Leveraging these environment variables helps applications (such as Neovim) more easily operate across different operating systems and distributions.

When Neovim starts, it iterates through the following sequence of base directories, in this order, looking for configuration and plugin files:

Location Description
$XDG_CONFIG_HOME personal configuration
$XDG_CONFIG_DIRS system-wide configuration
$XDG_DATA_HOME/site personal plugins
$XDG_DATA_DIRS/nvim/site system-wide plugins
$XDG_STATE_HOME session, swap, undo, etc
$XDG_RUNTIME_DIR files distributed with Neovim
$XDG_DATA_DIRS/nvim/site/after system-wide plugins
$XDG_DATA_HOME/site/after personal plugins
$XDG_CONFIG_DIRS/after system-wide configuration
$XDG_CONFIG_HOME/after personal configuration

Note that the last four directories basically just repeat the first four directories in the sequence, but in the reverse order, and with the addition of the after/ sub-directory. These should only be used when you need to override settings from system-wide configuration or plugins, which are loaded after the personal configuration. These should generally be ignored except for specific cases where they are needed.

Further note that although we included all of the base directories for completeness, we generally only care about the first directory (which we highlighted in bold), which is where we store our personal configuration files.

As mentioned earlier, the $XDG environment variables are used to help simplify Neovim configuration across platforms. The next step is to determine exactly what these environment variables mean on your system.

These locations can be determined by executing the vim.fn.stdpath function with the appropriate key, as defined below:

Environment Variable Key
$XDG_CONFIG_DIRS config_dirs
$XDG_DATA_DIRS data_dirs

For example, execute the following command to see the path to your configuration directory:

:lua vim.print(vim.fn.stdpath("config"))

or, if you prefer Vim functions:

:echo stdpath("config")

Now that we have an understanding of the directories where Neovim looks for configuration files, let's next look at what Neovim looks for in these directories.