Configuration

Where Neovim reads its config from, the environment variables that affect startup, and the runtime paths.

Config files

Neovim picks up exactly one initial config file, in this order:

1. $XDG_CONFIG_HOME/nvim/init.lua (default $XDG_CONFIG_HOME is ~/.config)
2. $XDG_CONFIG_HOME/nvim/init.vim

If init.lua exists, init.vim is ignored. After init.* runs, anything inside runtimepath is loadable via require() or :source.

runtime/doc/starting.txt documents the full startup sequence.

XDG paths (stdpath)

stdpath('<kind>') returns the directory for one of:

Kind	Default location	What lives there
config	$XDG_CONFIG_HOME/nvim	init.lua, user plugins, colorscheme overrides
data	$XDG_DATA_HOME/nvim	vim.pack-installed plugins, parsers, swap/, undo/
cache	$XDG_CACHE_HOME/nvim	shada, mempool caches
state	$XDG_STATE_HOME/nvim	persistent runtime state, log
log	$XDG_STATE_HOME/nvim/log	the log file
run	$XDG_RUNTIME_DIR/nvim.<pid>	server sockets

Implementation: src/nvim/os/stdpaths.c. On Windows, equivalent FOLDERID_* paths are used.

Environment variables

Variables consulted at startup (and runtime) that are worth knowing:

Variable	Purpose
NVIM_LOG_FILE	Override the log file path.
NVIM_LOG_LEVEL	One of DEBUG, INFO, WARN, ERROR.
NVIM_APPNAME	Switch the app name (and therefore all stdpath dirs). Useful to maintain multiple configs.
VIMRUNTIME	Override the runtime directory. Required when running an in-source build (./build/bin/nvim).
VIM	Older alias; rarely needed.
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME, XDG_RUNTIME_DIR	Standard XDG.
SHELL	Used by :!cmd, :terminal, and vim.system.
TERM	Set by the TUI based on what it advertises to the child.
COLORTERM	Detected by the TUI to enable truecolor.
NVIM	Auto-set in child processes spawned from inside Neovim — points at the parent's listen address. Used by nvim --remote and by plugin terminals.
NVIM_LISTEN_ADDRESS	Override the default listen address. (Deprecated in favor of --listen.)

Command-line flags

The most-used flags. The full list is in runtime/doc/starting.txt.

Flag	Purpose
--clean	Skip user config and shada. Reproducer mode.
-u <file>	Use <file> as the init file. -u NONE disables loading.
-U <file>	Same for the GUI init file.
--noplugin	Skip plugin loading.
--headless	No UI required.
--embed	Server with stdio msgpack-rpc; no built-in TUI.
--listen <addr>	Listen for additional RPC connections.
--server <addr> + --remote*	Connect to a running server.
-l <script>	Run a Lua script as a CLI; the editor exits after.
--luamod-dev	Bypass the precompile step for runtime/lua/vim/_core/.

Runtime path

'runtimepath' is the search path for runtime/-style content. The default order is:

1. $XDG_CONFIG_HOME/nvim
2. $XDG_DATA_HOME/nvim/site/pack/*/start/* (plugins under pack/start/)
3. $VIMRUNTIME
4. After-config locations.

Each directory may contain lua/, plugin/, colors/, syntax/, ftplugin/, parser/, queries/, doc/. The runtime walker (src/nvim/runtime.c, ~97k bytes) is responsible for finding files in this path.

Plugins installed by vim.pack end up in $XDG_DATA_HOME/nvim/site/pack/core/{start,opt}/. Plugins installed by other managers go in their own group.

Reading a config in tests

test/functional/testnvim.lua and test/testutil.lua start each nvim child with --clean. To reproduce a real-world config in a test:

local n = require('test.functional.testnvim')()
n.clear({ args = { '-u', '/path/to/init.lua' } })

Per-project config

Project-local config (.editorconfig, .luarc.json, .clang-format, etc.) is read by individual plugins, not by the editor proper. The most generic mechanism is :set exrc plus :trust (the secure modeline / project-config flow in runtime/lua/vim/secure.lua); few users enable it because of the trust prompt overhead.

Health checks

:checkhealth validates the user's installation. Each module that wants to participate provides runtime/lua/vim/<mod>/health.lua with a M.check function. Built-ins:

• :checkhealth nvim — core checks.
• :checkhealth lsp — LSP client + servers.
• :checkhealth treesitter — parsers + queries.
• :checkhealth diagnostic — config validation.
• :checkhealth provider.python (and friends) — the provider hosts.

The framework lives at runtime/lua/vim/health.lua.