Neovim on Windows + WSL

Since Neovim is the most admired editor, you definitely don’t want to miss this experience on Windows.

I will share my knowledge of installing Neovim on Windows and WSL with a shared configuration. This is extremely useful since nobody wants to manually keep multiple configurations of the same application up to date.

This is not a basic tutorial for Neovim or Linux. You have to figure out how to configure Neovim yourself. Since you are interested in installing Neovim on WSL, I assume you have basic Linux knowledge.

If you just want to try the possibilities of Neovim you can use a prebuilt configuration like kickstart.nvim, LazyNvim, AstroNvim or NVChad.

Expected configurations: None.

I will use <windows username> as a placeholder for your username on Windows and <linux username> for your username on WSL.

Keep in mind

If your Neovim configuration requires any dependencies, you have to install those on Windows and inside WSL.

Some Neovim plugins might not work on Windows, or they need additional configuration.

Windows

Terminal

Since Neovim uses a TUI (terminal user interface) you shouldn’t use cmd.exe as your terminal because its “features” might work against the Neovim TUI. The Windows Terminal technically works. Personally, I don’t like the experience on the Windows Terminal, but this is up to you.

I highly recommend WezTerm or Alacritty because those are extremely performant, feature rich and highly configurable.

If you’ve seen a multiplexer like tmux on Linux, this functionality is available using WezTerm out of the box. A multiplexer allows you to run multiple terminal sessions in one window.

Install Neovim

Open a terminal and run winget install Neovim.Neovim to install Neovim using the winget package manager.

You can use winget upgrade to update installed packages.

Next, you need to install git using winget install --id Git.Git -e --source winget.

You can open the window for environment variables by executing rundll32.exe sysdm.cpl,EditEnvironmentVariables.

Create an environment variable called HOME that resolves to C:\Users\<windows username> and another called XDG_CONFIG_HOME that resolves to C:\Users\<windows username>\.config and make sure those directories exist.

Your Neovim configuration can now be created in C:\Users\<windows username>\.config\nvim\ the entry point is a file called init.lua.

To learn about Neovim I recommend Vim As Your Editor by ThePrimeagen.

WSL

To activate WSL, execute OptionalFeatures.exe and activate “Windows Subsystem for Linux”. With WSL enabled, you can install a Linux distribution from the Windows Store.

If you decide to use Ubuntu (or another Debian based Linux) don’t use apt to install Neovim since you would get an ancient version.

Enter your WSL by running wsl in your terminal.

Install Git and Neovim using your distributions package manager (snapd, flatpak, pacman, yum, swupd, dnf, …).

To use your Neovim configuration from the Windows host system, create a symlink. The Windows C-drive is mounted on /mnt/c:

ln -s /mnt/c/Users/<windows username>/.config/nvim /home/<linux username>/.config/nvim

Do not create a new folder /home/<linux username>/.config/nvim.

How to only share parts of your configuration

Above, we share the whole configuration. It is also possible to have separate configurations and share only some individual Lua files.

For this, you don’t need the symlink to the nvim folder. Then create a file, shared.lua in your Windows configuration. On Linux, you create a symlink to this file. In both init.lua files, you import this file using:

require("shared")

Now this shared.lua is the only shared configuration file.