Installing and Diagnosing Neovim on Windows

Welcome. This first module establishes a reliable native-Windows baseline before adding any distribution, plugins, or personal configuration. The objective is deliberately narrow: launch Neovim from Windows Terminal, install the small set of command-line tools that will support the rest of the course, and learn the built-in commands that tell you what Neovim actually loaded.

For now, resist copying a prebuilt configuration or creating init.lua. In the next lesson you will create that file intentionally. Today’s value is having a clean reference point: when a future LazyVim, language server, or picker behaves unexpectedly, you will be able to separate a binary, PATH, runtime, configuration, and dependency problem quickly.

---

Install the stable Windows build

Use the stable Neovim release. Nightly builds are useful for testing Neovim itself, but they create unnecessary variables for a daily development environment.

Read the official installation guidance first; it confirms the supported Windows version and documents the package-manager route.

In Windows Terminal, preferably PowerShell, install Neovim:

winget install --id Neovim.Neovim -e

Close and reopen Windows Terminal after installation. A new shell receives the updated PATH; an already-running terminal usually does not.

Verify both which executable Windows will run and which Neovim version it is:

where.exe nvim
nvim --version

where.exe nvim is more important than it first appears. Over time, you might have a package-manager version, a Zip extraction, an old Vim extension bundle, or a work-managed copy on your PATH. Multiple results are not necessarily wrong, but the first result is the executable launched by nvim.

Now start a deliberately clean Neovim session:

nvim --clean

Inside Neovim, press Esc to ensure Normal mode, then run:

:version

The command-line nvim --version is best for confirming the executable from PowerShell. :version is useful once inside Neovim, especially while diagnosing a live session.

Quit with:

:q

If Neovim fails with a missing VCRUNTIME170.dll message, install the supported Microsoft Visual C++ Redistributable through your organization-approved software channel, then retry. Since Visual Studio is installed on this machine, the runtime will commonly already be present; only act on the explicit error.

---

Install the small external-tool baseline

Neovim itself is an editor, not an IDE bundle. It does not require Git, ripgrep, fd, Node.js, Python, or .NET merely to open and edit a file. That distinction matters because :checkhealth may report optional providers you do not need.

For the configuration and project navigation planned in this course, install these three tools now:

Tool	Why it belongs in the baseline	Verify with
Git	Cloning your configuration repository and installing plugin-managed components	git --version
ripgrep (rg)	Fast project text search; picker integrations use it rather than implementing search themselves	rg --version
fd	Fast filename discovery for project file pickers	fd --version

winget install --id Git.Git -e
winget install --id BurntSushi.ripgrep.MSVC -e
winget install --id sharkdp.fd -e

After reopening Windows Terminal if necessary:

git --version
rg --version
fd --version

This is intentionally not a “install every ecosystem runtime” step:

• Node.js is necessary for React development and some JavaScript tooling, but it is a project runtime with its own version-management considerations. Address it when TypeScript and React tooling are configured.
• .NET SDKs already belong to your existing backend workflow; Neovim will later invoke them rather than replace them.
• Python, Ruby, and Perl providers are optional bridges for plugins written in those languages. A warning about one of them is not a reason to install it automatically.
• A Nerd Font improves icons in a configured interface, but it is a terminal-display choice, not a Neovim command-line dependency.

This minimalism is one of the practical advantages of the Neovim model: you decide which capabilities enter the environment, and each executable remains independently inspectable.

---

Know the three locations behind a Neovim session

When a graphical IDE misbehaves, it can be difficult to distinguish settings, caches, extensions, and the product installation. Neovim exposes these boundaries directly.

Open Neovim normally:

nvim

Then run the following commands one at a time:

:echo stdpath('config')
:echo stdpath('data')
:echo $VIMRUNTIME
:set runtimepath?

These have distinct meanings.

Configuration directory

stdpath('config') reports where Neovim looks for your personal configuration. On a conventional native Windows setup it is normally under:

%LOCALAPPDATA%\nvim

The configuration file you will create next lesson belongs there as init.lua. At this point, the directory or file may not exist. That is expected.

Data directory

stdpath('data') reports the per-user data location, normally resembling:

%LOCALAPPDATA%\nvim-data

Plugin managers typically place downloaded plugins, registries, and generated state somewhere under this general area. Treat it as generated local state rather than the source-controlled definition of your setup.

Runtime directory

$VIMRUNTIME identifies the runtime files that ship with the Neovim installation: help documents, syntax and filetype support, built-in Lua code, standard plugins, and health checks. If this location is wrong or unavailable, Neovim may start but lose seemingly fundamental behavior.

Runtime path

'runtimepath' is an ordered search list. It includes the runtime directory but can also include configuration-related locations, site directories, and later plugin directories. Neovim searches these locations to find many resources.

The important diagnostic distinction is:

• $VIMRUNTIME answers: where are Neovim’s bundled runtime files?
• 'runtimepath' answers: where will this running session search for runtime files?

You do not need to memorize every path printed by :set runtimepath?. The habit is to inspect it when Neovim cannot find a plugin, a syntax file, a health check, or an expected Lua module.

Two additional commands complete the first troubleshooting toolkit:

:scriptnames
:messages

:scriptnames lists scripts sourced during startup. Once you have an init.lua and plugins, it is concrete evidence of what loaded and in what order. :messages displays warnings and messages accumulated in the current session. Use it immediately after a startup error, a failed command, or a suspicious plugin load.

For a clean comparison point, quit and launch:

nvim --clean

Then repeat :scriptnames and :messages. Clean mode avoids your user configuration and plugins. Today, before a configuration exists, normal and clean sessions should be nearly indistinguishable. Later, that comparison will isolate whether a problem belongs to Neovim itself or to your setup.

---

Use health checks as a focused diagnostic report

Neovim’s health framework checks conditions that features and plugins depend on. Think of it as environment diagnostics, not as a pass/fail exam that demands every optional integration be installed.

Back in Neovim, run:

:checkhealth

A report opens in a buffer. Read it top to bottom once, but triage findings rather than fixing every warning. Close the report with q.

For the baseline installed today, these are the useful interpretations:

Report type	Meaning	Appropriate action now
ERROR mentioning runtime files or failed core checks	Neovim may be incompletely installed or resolving an unexpected executable	Check where.exe nvim, $VIMRUNTIME, and reinstall if needed
ERROR for git, rg, or fd after installation	The executable is not visible to Neovim’s inherited PATH	Restart Windows Terminal; confirm each command in PowerShell
WARNING for Python, Ruby, or another provider	An optional integration is unavailable	Leave it alone unless a chosen plugin later requires it
WARNING about clipboard or a terminal-specific feature	The current terminal cannot provide an optional capability as expected	Record it; investigate only if it blocks an actual workflow
Plugin-specific issue	Relevant only after that plugin has been installed	Run that plugin’s targeted health check when configuring it

Run the built-in Neovim health check alone:

:checkhealth vim.health

Later, when language tooling exists, a focused command such as the following will be much more useful than scanning an all-plugin report:

:checkhealth vim.lsp

A targeted health check reduces noise and makes an issue actionable. For example, when C# support is added, inspect the language-server health report and its exact executable findings rather than responding to unrelated Ruby-provider warnings.

---

A repeatable Windows troubleshooting sequence

At the end of this session, you have a compact diagnostic sequence worth keeping in a notes file or your eventual configuration repository:

1. In Windows Terminal, run where.exe nvim and nvim --version to verify the executable and version.
2. Start nvim --clean to determine whether the core editor works without personal configuration or plugins.
3. In a normal Neovim session, inspect :messages for startup output.
4. Check :echo stdpath('config') to find the expected configuration location.
5. Check :echo $VIMRUNTIME and :set runtimepath? when files, help, syntax, or plugins cannot be found.
6. Use :scriptnames to establish what actually loaded.
7. Run :checkhealth broadly at first, then use targeted checks such as :checkhealth vim.health or :checkhealth vim.lsp.

This sequence is more reliable than deleting directories or reinstalling plugins at random. It gives each problem a layer: shell environment, Neovim binary, runtime, configuration, plugin, or external executable.

---

You now have a native Windows Neovim installation, Git plus the two search tools needed for efficient project work, and a practical way to inspect the running editor rather than guessing about it. The key ideas are that Neovim’s configuration, generated data, bundled runtime, and ordered runtime path are separate things—and that health warnings must be interpreted in the context of the feature you actually intend to use.

Next lesson, you will create a minimal Lua configuration with one option, one keymap, and one autocommand. You will then use the diagnostic commands from today to verify exactly where that configuration lives and when each setting takes effect.