NvChad: a Neovim base config split into a framework and a starter

The split between NvChad and nvchad/starter

The README is explicit that this repository is not the thing you clone into your Neovim config directory. It states that NvChad "is supposed to be used with its starter config", so the main repo can be imported as a plugin through lazy's import feature, after which your configuration can call this repo's modules such as autocmds. That is an unusual arrangement for a Neovim distribution. Most of them ask you to back up an existing config, clone one repository, and start editing it. NvChad instead keeps the framework in one repository and the user-facing entry point in another, which is what makes the update story work: the framework can move forward without your edits being overwritten, because your edits are not supposed to be in the framework at all. The README describes the intent directly, saying users "would have to keep a track of every change" without the custom config split, and that custom modifications are gitignored so they do not get in the way. The cost of that design is a second repository to understand before you have written a line of Lua.

What lazy loading actually buys you

The performance claim in the README is specific and testable: "Lazy loading is done 93% of the time", meaning plugins are not loaded by default and instead load on specific commands and events. The same paragraph reports a startuptime of around 0.07 seconds on a Pentium at 1.4GHz with 4GB of RAM and an HDD, and the opening description gives a range of around 0.02 to 0.07 seconds. Those numbers come from the project's own testing on its own hardware, so treat them as the author's measurement rather than a guarantee for your machine. What matters for adoption is the mechanism, not the digits: the plugin set is wired so that telescope, nvim-tree and the rest are pulled in on demand rather than at startup. That is the reason the project exists at all. The README's history section says the author was working on a 1.4GHz Pentium with 4GB of RAM and found VS Code too heavy, Doom Emacs slow, and LunarVim's documentation too much to read, and built the config he wanted instead. The lazy loading is the direct answer to that constraint. If your machine is not constrained, the benefit is smaller but the startup time is still real.

The UI layer: base46, NvChad UI and Tabufline

A large part of what you see is not Neovim and not a third-party plugin. The README lists base46 as the project's own theme plugin and NvChad UI as its own lightweight UI plugin, which supplies statusline modules, tabufline (a per-tab bufferline), cheatsheets, the NvChad updater, terminal buffer hiding, and the theme switcher. The statusline is described as written from scratch. Around ninety themes are available according to the README's theme section. The remaining UI is assembled from well-known plugins: nvim-tree.lua for file navigation, telescope.nvim for fuzzy finding and previews, nvim-web-devicons for icons, gitsigns.nvim for diffs, nvim-lspconfig with mason.nvim for LSP, nvim-cmp for completion, nvim-treesitter for syntax highlighting, nvim-autopairs, indent-blankline.nvim, LuaSnip with friendly-snippets, and which-key.nvim for the popup key map. The trade-off is that when something in the statusline or tabufline misbehaves, you are debugging NvChad's own code rather than a plugin with a broad user base and its own issue tracker. The upside is that the pieces are designed to look consistent, which is the stated goal.

Installing NvChad with the starter config

The README does not carry install commands itself. It links to nvchad.com/docs/quickstart/install for installation, so the authoritative steps live on the documentation site and in the nvchad/starter repository. What the README does establish is the requirement and the shape of the setup: the badge at the top of the repository lists Neovim 0.11 as the minimum version, and the description says the main repo is imported as a plugin via lazy's import feature. That means the entry point you clone is the starter, and the framework arrives as a dependency of it. A typical lazy specification for importing a config repository looks like this, and the import key is the part the README refers to:

A first real use: opening a project and finding a file

Once the starter is in place and Neovim starts without errors, the fastest way to confirm the setup is to check the three things the README advertises. Start Neovim in a project directory and the file tree from nvim-tree.lua should be reachable through its mapped key; the README's features page and the cheatsheet plugin are the reference for what those keys are, and the README does not print the key table itself. Then use telescope.nvim for fuzzy finding, which the README describes as a "fuzzy file finder, picker, sorter, previewer and much more". Finally, open the cheatsheet, which the README lists as an NvChad UI plugin, to see the mappings without leaving the editor. If the tree, the picker and the cheatsheet all respond, the import worked and lazy loading is doing its job. If Neovim starts but the UI looks like stock Neovim, the import is the first thing to check, because the theme and statusline come from base46 and NvChad UI rather than from Neovim itself.

Where NvChad is the wrong tool

The version floor is the first hard limit. The repository badge states Neovim 0.11 as the minimum, so a distribution or a remote host pinned to an older Neovim will not run this configuration as documented. The second limit is the split itself. If you want one directory that contains your entire editor configuration and nothing else, the framework-plus-starter arrangement works against you: part of your setup lives in a repository you are not meant to edit, and the parts you are meant to edit are gitignored. Users who like to read every line of their config will find that the interesting behaviour is in an imported module. The third limit is the documentation surface. The README points outward for installation, features and the full plugin list rather than reproducing them, so anyone who expects a single file to answer every question will be reading the website anyway. None of these are defects exactly, but each one is a reason someone picks a different config.

NvChad compared with Lunarvim and Doom Emacs

The README's own history names the two projects that shaped it: Doom Emacs, which the author found pretty but slow and hard to navigate in its documentation, and LunarVim, whose documentation he did not want to read. The difference in approach is worth stating plainly. Doom Emacs is an Emacs configuration with its own module system and package manager, so adopting it means adopting Emacs. LunarVim is a Neovim distribution that historically shipped as a single installable layer with its own defaults and its own plugin set. NvChad's distinguishing choice is the starter split described above, plus the decision to write its own theme and UI plugins rather than configure existing ones. If you want the smallest number of moving repositories, a single-repo distribution is simpler. If you want the base to be updatable independently of your edits, NvChad's layout is the one that tries to guarantee it.

Licence, updates and what maintenance costs

NvChad is licensed GPL-3.0, which is a copyleft licence, and it is worth understanding what that means for a config you copy and redistribute rather than for private use. If you publish your configuration as a derivative, the licence terms apply to what you publish. This is not legal advice; read the LICENSE file in the repository for the actual terms. On maintenance, the repository is not archived and the last push was on 2026-07-03, so the codebase has moved recently. The release history is a different picture: v2.5 is dated 2024-03-09 and v2.0 before it on 2023-03-15, so tagged releases are infrequent and the default branch is where current work happens. That matters for how you pin your setup. The README notes that NvChad UI provides the NvChad updater, and the split layout is designed so that framework updates do not collide with your custom directory. Budget time for the fact that a fast-moving default branch plus a slow release cadence means your configuration is tracking a branch, not a version.

Editorial conclusion

Adopt NvChad if you want a themed Neovim base with lazy loading and you are willing to keep your edits inside the starter config, because that is the layout the project documents. Do not adopt it if you want a single self-contained config directory you own end to end, or if you are stuck below Neovim 0.11. Before committing, verify your Neovim version against the 0.11 badge, clone nvchad/starter and confirm that the custom directory it tells you to edit is where you actually want your changes to live.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. NvChad/NvChad on GitHub
3. Project website
4. README
5. Releases