How do I create a project-specific Lua config that Neovim loads automatically from the project directory?

Explanation

Neovim supports project-local configuration via a .nvim.lua file placed in the root of your project. When you open a file from that directory, Neovim can load it automatically — but only after you have explicitly trusted it, preventing arbitrary code execution from untrusted directories.

How it works

1. Create .nvim.lua in your project root with any Neovim Lua config:

" .nvim.lua
vim.opt_local.tabstop = 2
vim.opt_local.shiftwidth = 2
vim.opt_local.expandtab = true
vim.opt_local.colorcolumn = "120"

2. Open a file from the project directory. Neovim may warn you the file is untrusted.

3. Trust the file explicitly:

:trust /path/to/project/.nvim.lua

You can also trust the current directory's .nvim.lua with :trust and then confirm when prompted, or use the interactive dialog Neovim presents.

4. On subsequent opens, .nvim.lua loads automatically.

Tips

• Neovim searches the current directory and all parent directories for .nvim.lua, .nvimrc, and .nvim.vim.
• Requires vim.o.exrc = true (or :set exrc) to enable local config loading.
• Trusted paths are stored in $XDG_STATE_HOME/nvim/trust. To revoke, run :trust! {path}.
• Use vim.opt_local rather than vim.opt to keep settings buffer-local rather than global.
• Neovim 0.9+. For Vim compatibility, use .exrc with Vimscript instead.