NormalNvim: a Neovim distribution designed to be forked and kept
A normal Neovim distribution
At a glance
- What is it?
- NormalNvim is a Lua Neovim distribution that expects you to fork it and treat it as the base of your own configuration, with a bundled toolchain for the top 12 languages and a rollback command for updates. It suits developers who want batteries included without losing control, and it is the wrong choice for anyone who wants a minimal config.
- Who is it for?
- Adopt NormalNvim if you want a working LSP, debugger, test runner and Treesitter setup on day one and are willing to fork the repository and treat it as the long term home of your configuration, which is how the project describes its intended use. Do not adopt it if you want a minimal Neovim setup or if you cannot keep a fork updated, since the project is explicitly not designed to be pulled from upstream often.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 66 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 20, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The fork is the installation model, not an afterthought
The first line of the readme is a version constraint: you need Neovim 0.12 or later. Everything after that is about ownership.
The philosophy section states the position directly. You are expected to fork the project before cloning it, so that you are the only one in control, and the neovim appimage is recommended. The stated intent is that this is not a distro you are expected to update often from upstream, and that it is meant to be used as a base to create your own distro.
That framing explains the whole design. It is described as a normal nvim config you can trust will never unexpectedly break while you are working, with nothing flashy and nothing brightful, just bread and butter.
The installer exists for Linux, MacOS and WSL:
wget -q https://raw.githubusercontent.com/NormalNvim/installer/main/installer.sh && chmod +x installer.sh && ./installer.shManual cloning is supported too, and the readme repeats the recommendation to fork and clone your own fork:
git clone https://github.com/NormalNvim/NormalNvim.git ~/.config/nvimOn Windows the path differs:
git clone https://github.com/NormalNvim/NormalNvim.git %USERPROFILE%\AppData\Local\nvim && nvimThe readme also notes that optional dependencies are only necessary if you installed by cloning manually, and links a dependencies page for the full set of features.
Twelve languages preinstalled and preconfigured
The feature list is where this distribution separates itself from a bare Neovim install.
IDE parsers are shipped preinstalled and preconfigured, covering linters, formatters, LSP and Treesitter for the top 12 most popular programming languages. The point is that the toolchain works out of the box rather than requiring you to assemble and debug each piece.
The IDE tooling is also bundled. Compiler.nvim handles compilation, DAP is the debugger, Neotest is the test runner and Dooku.nvim generates documentation. Shipping these as part of the distribution means a new user gets a working compile, debug and test loop rather than four separate plugin searches.
Plugins are loaded lazily, and every feature is described as a small plugin, which is the mechanism behind the modularity claim. Plugins are also described as self-contained, so deleting one you do not want does not require unpicking shared configuration.
Two claims deserve a note. The readme says any plugin the distribution ships can be used in any other distro, which follows from the self-contained and lazy-loading design rather than from any special packaging. And it states that the project does not hide or abstract things from you, with code comments meant to guide customization.
For anyone evaluating this, the top 12 languages claim is the thing to test against their own stack. If your language is in that set, the value of the distribution is high. If it is not, you are back to assembling the toolchain yourself.
Plugin freeze and rollback as the answer to update fear
Distributions of this kind usually get abandoned for one reason, and a configuration breaks during an update. NormalNvim addresses that in two ways that are visible in the command list.
The first is the plugin version freeze. You can choose between stable and nightly update channels, and if you prefer you can use the :DistroFreezePluginVersions command to write your current plugin versions into lazy_versions.lua, creating your own stable set.
The second is the rollback. The :DistroUpdateRevert command reverts the last :DistroUpdate, and the readme states you can recover from a distro update that way.
The commands themselves come from distroupdate.nvim, and the table spells out the cost of each one plainly. :DistroUpdate pulls from the git origin and local uncommitted changes will be lost. :DistroFreezePluginVersions saves the current plugin versions into lazy_versions.lua.
That last warning is the design constraint in one sentence. Because the intended workflow is a fork that you own, the update command operates on a git remote, and an update that overwrites local work is a real failure mode. A team with uncommitted changes in their Neovim config should freeze and commit before pulling.
The hot reload feature belongs to the same family. Changes to your config are reflected in the running Neovim instance in real time without a restart, which shortens the loop between editing a keymap and trying it.
Where the configuration actually lives
The readme answers the common customization questions by naming files, which is the most useful thing it does for someone deciding whether they can live with this setup.
For the user interface, the readme says the plugin heirline is used to create the interface, and that components can be reordered or changed in plugins/2-ui.lua. If you prefer the classic vim appearance you can delete the plugin.
For a colorscheme, you add the theme in plugins/2-ui.lua, reopen nvim, and set it in base/1-options.lua. Installed themes can be previewed with the space key followed by ft, and the space key is described as showing everything you can do through the wiki page of basic mappings.
For icons, you need the nerdfont version of your font installed in your terminal, or you can specify your own in base/icons/nerd_font.lua. The Tokyo Night theme is the default.
For animations, mini.animate can be deleted to turn them off, or you can read the plugin documentation to disable only some of them.
The top level of the repository matches this description. There is an init.lua at the root, a lua/ directory for the Lua modules, and configuration tooling: a .stylua.toml and .styluaignore for formatting Lua, a selene.toml and .selene-schema.yml for linting. The presence of a formatter config and a linter config in the root tells you the project expects contributors to run the same tools it does.
Two configuration habits the readme asks you to adopt
Two small habits are embedded in the distribution rather than left to you, and they will affect your first hour with it.
The first is the default mapping layout. The distribution uses qwerty by default, and a colemak-dh variant is documented separately. If you type on Colemak, the default layout is wrong for you until you switch.
The second is the language model integration. The readme explains how to use the Ask chatgpt command by setting an environment variable on your operating system, with the API key obtained from the chatgpt website:
OPENAI_API_KEY="my_key_here"That is the only environment variable the project documents, and it is worth noticing what it implies. A user who installs the distribution and sets an API key is sending editor context to a third party service, and the decision belongs to the user rather than to the distribution. The readme does not describe what context is sent, whether it is sent on every request, or whether it is sent at all when the variable is unset, so treat the key as opt in and read the plugin's own documentation before relying on it in a codebase with confidential material.
For diagnosing problems, the readme points at the :checkhealth base command, which is run inside Neovim.
For plugin questions in general, the FAQ directs users to the astrocommunity repository for help installing and configuring most plugins, which is a reasonable place to look since the plugin set overlaps with that ecosystem.
What the distribution does not promise
Several things are conspicuously absent from the readme, and the gaps are consistent.
There is no statement of which plugin manager is used, though the lazy_versions.lua filename referenced by the freeze command and the lazy loading claim point at lazy.nvim. There is no list of the twelve languages in the IDE parsers section, so you have to check whether yours is included before committing. There is no compatibility statement for older Neovim versions beyond the 0.12 requirement, and no changelog file at the repository root.
The readme also does not describe a migration path from another distribution. For a team moving from an existing setup, the mechanics of what to copy, what to drop and what conflicts appear are not documented here.
The phone friendly claim deserves a caveat too. Installing on Android Termux is mentioned as possible, but the readme does not describe which optional dependencies apply on that platform, so it is a statement of possibility rather than a documented path.
Finally, the project asks for help with marketing, which is a small but telling detail. This is a community project with a Discord server and a wiki, and the maintainers are candid that distribution is a challenge. That is fine for a hobby project, and it is worth factoring into a decision about how much you depend on it.
Maintenance state and the GPL-3.0 licence
The repository is not archived, and the last push was on 2026-08-17.
The tagged releases are slower than the pushes. v4.5.2 came on 2026-02-25, v4.5.1 on 2025-11-11, and v4.5.0 also on 2025-11-11, so two of the three most recent tags share a date and the newest tag is about eight months older than the last commit. That pattern fits the stated philosophy of a distribution you are meant to fork rather than pull, since a released version matters less when the expectation is that you track your fork.
The licence is GPL-3.0, with a LICENSE file at the repository root. For a configuration that lives in your own home directory on your own machine, the practical effect is minimal, because you are not distributing it. The case that matters is the fork: your fork is a derivative work of a GPL-3.0 project, so if you publish your configuration publicly you are publishing GPL-3.0 licensed material. That is a normal outcome for a configuration of this kind, but it should be a decision rather than a surprise, especially for anyone whose employer has a policy on open source contributions.
The homepage is normalnvim.github.io, the wiki is on the repository, and the source of the update commands is distroupdate.nvim by a separate author, which is worth knowing since the command behaviour such as losing uncommitted changes lives in that plugin rather than in this repository.
Editorial conclusion
Adopt NormalNvim if you want a working LSP, debugger, test runner and Treesitter setup on day one and are willing to fork the repository and treat it as the long term home of your configuration, which is how the project describes its intended use. Do not adopt it if you want a minimal Neovim setup or if you cannot keep a fork updated, since the project is explicitly not designed to be pulled from upstream often. Before you commit, confirm you are on Neovim 0.12 or later, read the dependencies page if you installed by cloning rather than with the installer, and set OPENAI_API_KEY in your environment if you intend to use the Ask chatgpt command.
Frequently asked questions
What Neovim version does NormalNvim require?
The readme states you need Neovim 0.12 or later, and the project recommends using neovim's appimage. The configuration itself is written in Lua.
How do I install NormalNvim on Linux, MacOS or WSL?
You can run the installer script with wget, chmod and the shell script, or clone the repository manually into ~/.config/nvim. The readme strongly recommends forking the repository and cloning your own fork rather than the upstream one.
How do I roll back a NormalNvim update?
Use the :DistroUpdateRevert command, which reverts the last :DistroUpdate. Note that :DistroUpdate pulls from the git origin and local uncommitted changes will be lost.
How do I freeze plugin versions in NormalNvim?
Run :DistroFreezePluginVersions, which saves your current plugin versions into lazy_versions.lua. You can also choose between stable and nightly update channels instead.
How do I set up the Ask chatgpt command in NormalNvim?
Set the OPENAI_API_KEY environment variable on your operating system, using an API key obtained from the chatgpt website. Icons also need a nerdfont version of your font, or you can specify your own in base/icons/nerd_font.lua.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/normalnvim-normalnvim)Was this useful?