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_HOME | config |
| $XDG_CONFIG_DIRS | config_dirs |
| $XDG_DATA_HOME | data |
| $XDG_DATA_DIRS | data_dirs |
| $XDG_STATE_HOME | state |
| $XDG_RUNTIME_DIR | run |
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.