# Introduction

One gloomy Sunday afternoon, I tried to install Neovim and VSCode Neovim in my work setup (Windows 10 & Ubuntu WSL). Unfortunately, I was faced with many issues and I could not get this configuration to work properly.

There are different ways available to install Neovim on Ubuntu. In my case, the only solution that worked was to install Neovim via AppImage and configure everything in a very specific way. However, you should note that AppImage is not the reccomanded way to install Neovim.

So if you are just starting out, you should follow these instructions to install Neovim using the Ubuntu PPA. You can then jump to "Step 4" of this guide to wrap up the setup.

If instead you tried installing Neovim using the PPA but are still experiencing some issues, then you should give a try to this guide. This guide will specifically install and setup Neovim using the AppImage.

# Who this guide is for

If you are on Windows (10 or 11) and are using WSL for your daily development.

If you are trying to get into Neovim, you are coming from VSCode, but you are not fully ready to switch yet.

Then this guide is for you! I will show you how to get regular Neovim setup in WSL and how to get it to work also inside VSCode.

# Prerequisites

Have WSL correctly installed and configured.

Make sure the latest version of wsl is installed (wsl --update) and make sure that you are on version 2 of wsl (wsl --set-default-version 2)

# Step 1: Configure WSL

Make sure that Ubuntu is selected as the default version in WSL

wsl --list --all

If not, set it as default

wsl --setdefault Ubuntu #or whatever is the name of your ubuntu distro

# Step 2: Prepare Ubuntu

Older versions of Ubuntu can cause some troubles (especially we we will configure the VSCode part). This guide has been tested with Ubuntu 24.04. I was personally having some issues with Ubuntu 22.04, so upgrading fixed it for me. If upgrading Ubuntu is not an option for you, you can try and skip this step.

Inside Ubuntu, check the version that you have currently installed:

lsb_release -a

If the version is lower than 24.04, update Ubuntu WSL. Inside Ubuntu type

sudo apt update && sudo apt full-upgrade

Now exit Ubuntu and in your Windows PowerShell fully shut down Ubuntu

wsl --terminate Ubuntu #or whatever is the name of your ubuntu distro

Finally, restart Ubuntu and run the install by typing

sudo do-release-upgrade

Once done, make sure that the update was successful and that you are on v24.04

# Step 3: Install Neovim

We can now install Neovim in WSL Ubuntu.

We are going to setup Neovim via a AppImage. No installation is needed. We will just download and run the image.

The reason why we use the AppImage is because Ubuntu might not have the latest version of the Neovim Package available. This way ensures that we get the latest stable version.
Neovim is rapidly developing, so using the latest stable version is what we want to do here (especially for the last step of this guide where we are going to use Neovim VSCode)

To be able to run AppImage, we need to make sure we have libfuse2 installed

sudo apt install libfuse2

Now we can move on to the actual installation.

Go to the Neovim Website ⇒ Install Now (link). Scroll down to the AppImage section.

# Download the app image
  curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim.appimage
  # Add permissions to run the appimage file
  chmod u+x nvim.appimage
  # Run the app image
  ./nvim.appimage

This should open Neovim! Type :q<Enter> to exit.

This is nice! However this will require to run Neovim using the full file path (eg: ~./nvim.appimage). So we want to expose Neovim globally to just run nvim to start it.

To do that, we first move the nvim.appimage to a better directory

sudo mkdir -p /opt/nvim
  sudo mv nvim.appimage /opt/nvim/nvim

Then we need to add this to our PATH. To do that, we need to edit the shell config file.

For WSL Ubuntu, by default the shell is Bash. So we need to edit the ~/.bashrc file.

Open the shell config file with any text editor. In this case I am using nano, but you can also use vi (should be already installed!)

sudo nano ~/.bashrc

Scroll all the way to the bottom and add the following line

export PATH="$PATH:/opt/nvim/"

This will append the /opt/nvim/ directory (where we have our Neovim appimage file) to the PATH.

Exit nano (ctrl + x , y , <Enter>) and run the source command to refresh the shell

source ~/.bashrc

now, running nvim should open up Neovim from any directory!

Finally, we want to add a configuration folder. Here we will store our Neovim configuration.

First of all check if you already have a .config folder in your root (cd ~/.config). If not, you can simply create it by sudo mkdir ~/.config . cd into the config directory.

Neovim will look into this .config directory for a nvim directory. So we can create it by sudo mkdir nvim.

Here in this folder we can add Neovim configurations (vi init.lua). But this is besides the scope of this guide.

# Step 4: Configure Neovim VSCode

Now that we have Neovim installed correctly, we want to be able to use it inside our VSCode.

NOTE: Before proceeding, make sure that wsl --list --all has "Ubuntu" set as your default WSL. For more info, view "Step 2" of this guide.

To start, open up VSCode (in WSL!!), go to the extensions tab. Here you can search for "VSCode Neovim" or you can simply install it from this link.

To make Neovim work with WSL, we need to do a couple more steps. First of all, open up VSCode settings (ctrl + ,). Click on "neovim" from the left side menu.

Now we need to configure 2 important settings:

1. Set "Use WSL" to true

   

1. Manually set the "Neovim Executable Path: Linux". In that box we have to specify the path where we installed Neovim earlier. If you recall, we installed it in /opt/nvim/nvim. If you are unsure of where your Neovim is installed, you can just type in which nvmin in the terminal and copy the output in the field. You should now have something like this:

   

Restart VSCode to apply the changes, open up a file, and you are done! Congratulations, you are now using Neovim with VSCode!